% fwebman.tex:  --- USER'S MANUAL for FWEB ---

% Version 1.30 (June 15, 1993)

% If you want to get the user's manual, you can use the make file FWEB.mk
% that is provided with FWEB. You simply say
%
%	make -f FWEB.mk fwebman
%
% NOTE: This will launch a 180 page job to the line printer! Try this out
% first with 
%
%	make -n -f FWEB.mk fwebman
%
% to make sure it's going to do what you want.

% In case you can't use the make file, here are more details about fwebman.tex
% This file must be used with the files indexing.tex, indexmac.tex, and mx.sty,
% which are needed for the index and are provided with the FWEB distribution.
% When you say "tex fwebman", you will get the files fwebman.dvi and
% also fwebman.idx. Printing fwebman.dvi produces the manual, including a
% table of contents. The latter file is intended to be used with the
% utility makeindex. Say "makeindex -s mx.sty -p any fwebman.idx"; you will get
% the LaTeX file fwebman.ind, which can then be processed with LaTeX to
% give the index for the users manual. The sequence of operations should be
%	tex fwebman
%	makeindex -s mx.sty -p any fwebman.idx
%	(print fwebman.dvi)
%	latex fwebman.ind
%	(print fwebman.dvi)
% This sequence is to avoid overwriting the dvi file, and ensures that
% makeindex gets the appropriate page number from fwebman.log.  Again, the
% provided make file handles all this automatically.

\newif\iftypesetfwebmac

% Appendix F is provided for typesetting the FWEB macro package fwebmac.web
% directly into the manual; however, by default this appendix is turned
% off.  To turn it on, remove the comment symbol from the next line:

%\typesetfwebmactrue

%			*	*	*

\def\PAGESTART{8}

\def\contentsfile{fwebman.cts}
\input fmanmacs
\Wbegin[]{article}{1em}{1em}{\contentsfile}{{\&}{\|}{\\}{\\}{\\}{\@}{\.}{\.}}


\def\Wtitle{--- FWEB USER'S MANUAL ---}

\doctitle{User Manual}

\vskip 15pt plus 3pt minus 3pt

\maxsctn{-1}{19}

\section INTRODUCTION.[1.2]

\parinserto{6}{4}{0.58}
{{\ssbf FWEB} understands C, C{\ttitlefont ++}, Fortran--77, Fortran--90,
Ratfor, and \TeX.} 

This manual describes how to write programs in Knuth's ^^{Knuth, Donald}
\.{WEB} system, ^^{\>{WEB}}
as adapted and extended by J.~A. Krommes ^^:author!present: ^^{Krommes,
John~A.} 
to handle the programming languages of \Fortran\ (including both
\Fortran--77 and \Fortran--90),
\Ratfor, \C, \Cpp, and~\TeX.  We shall 
call this new version \FWEB\ ^^:\>{FWEB}:
when necessary, but generally we'll just refer to the \WEB\ system.  This
adaptation is a substantial modification of S.~Levy's \C~version \.{CWEB}
^^{Levy, Silvio} ^^{\>{CWEB}}
of \.{WEB}, which in turn was a complete rewrite in~\C\ of Knuth's original
\Pascal\ source. (\TeX~is written in the
original \Pascal\ \WEB.)  The principal design contributions to this
version of~\WEB\ are (1)~the concept of a current
\It{language}, so that one can process code written in multiple languages
in the same \.{WEB} run; (2)~new production rules for
\Fortran, \Ratfor, and~\TeX\ (and some modifications of Levy's rules for~\C);  (3)~a
\hbox{\C-like} built-in macro preprocessor; and (4)~the ability to directly
translate \Ratfor\ into \Fortran. In addition, many miscellaneous details
have been changed and a variety of convenience features have been added.
For example, a general style-file mechanism allows the user to customize
various actions of the system.

This manual covers quite a breadth of material, from the most introductory
to very advanced. To help identify the level of difficulty, the sections
are marked with~0, 1, or~2 dangerous bends (here shown as \dbend) a~la the
\TeX book. 

\subsection Previous authors, and the structure of this manual.

The \WEB\ system and this manual have evolved through contributions of
several authors, principally Knuth and Levy, 
^^{Knuth, Donald} ^^{Levy, Silvio} ^^:author!previous:
and the flavor of the system
is best captured with those authors' original words. Levy attempted to
highlight Knuth's original text by indenting it. Quoting from Levy's
manual, ``The bulk of this document \bdots\ consists of quotes from Knuth's
memo `The \.{WEB} System of Structured Documentation'; these quotes are
clearly distinguished by their indentation, and apart from \[such
substitutions as `code' for `Pascal'\], all other changes to them are
explicitly indicated. This also serves to indicate which commands and
features are common to all versions of \WEB\ and which are characteristic
of this version (of course if you're new to \WEB\ you don't have to worry
about this).'' In practice, new users of \WEB\ seem to find the indented
style somewhat confusing; furthermore, the length of this manual has grown
to a point where more than 50\% of the text is new.
Therefore, in an attempt to accomodate everyone,
this user manual can be \TeX ed in two ways, depending on the setting of
the \TeX\ macro \.{\\ifbilevel}, ^^:\CS{ifbilevel}:
defined near the beginning of the macro package \.{fmanmacs.tex} for this
manual.  By default, that switch is false and most
indentation is suppressed. (A few of the most significant quotes are
indented in both formats.)  To obtain the indented style, say
\.{\\bileveltrue}. ^^:\CS{bileveltrue}:
In the bilevel mode, we shall preface Levy's remarks by
``{\bileveltrue \Levy:}'', and we shall feel free to interject additional
remarks by enclosing them in square brackets or to skip extraneous material
by using an ellipsis. The brackets and ellipses are also suppressed
when the \.{bilevel} switch is false.

\subsection The origins of \FWEB. ^^{\>{FWEB}!origins of}

\It{(The contents of this subsection are totally irrelevant to the narrow
goal of learning to use \FWEB.  But they might be of some ``cultural''
interest.)}

\FWEB\ was born of necessity.  One of the focuses of my research in
theoretical plasma physics has been the construction and solution of
so-called ``statistical closure approximations,'' the most famous example
of which is Kraichnan's 1959 direct-interaction approximation~(DIA). 
^^{direct-interaction approximation}
At some point around 1985 I decided that further progress would benefit
greatly from numerical solutions of the DIA and related closures applied
specifically to plasma turbulence.  (Kraichnan, Herring, and others had
long before done the analogous calculations for neutral-fluid turbulence.)
So I began writing my \.{DIA} code---in standard \Fortran.  The result was a
disaster.

I needed extensive memory allocation facilities, but \Fortran--77 doesn't
provide them.  I simulated them using tricky array manipulations, but the code
was difficult to debug and to understand. I wanted complicated data
structures, but again \Fortran--77 wasn't up to the task.  
^^{language!Fortran:\FORTRAN!inadequacy of}
Ditto for simple
string manipulations, communication with the command line, and transparent,
easy-to-write I/O statements.  In other words, I didn't want \Fortran--77
at all; I wanted~C!\ \  So I threw away a year's worth of work and started
over.

The second time around, I at least had a better sense of the scale of the
project---it was large.  Also, upon looking
back at my original attempt, I realized that I couldn't understand the code
at all, even though I had been fairly liberal with \Fortran-style comments.
Looking ahead, I also realized that graduate students would likely become
involved.  Since I have strong feelings about wanting my students to
actually do physics instead of just computing, it became imperative to
write the code using the most powerful documentation scheme available so
they could quickly understand how it worked and could modify it as easily
as possible.  Knuth's article on ``Literate programming''\cite{Knuth} had
already provided a ``religious experience'' 
^^{religion}
for me when I read it several years
previously, tempered only by the fact that I hadn't been in a computing
phase at that time.  But faced with the demands of the \.{DIA} project,
Knuth's excellent points all came back and I realized that \WEB\ was the
natural choice.  Luckily, Levy had just announced his beautiful \CWEB, 
^^{Levy, Silvio}
so everything seemed to be in place.

Then, another setback.  One of the important characteristics of plasma, as
opposed to incompressible fluid, turbulence is the presence of linearly
propagating waves---described most naturally with complex numbers.
Unfortunately, C~doesn't have an intrinsic \&{complex} type.  \Cpp\ can
easily be taught complex arithmetic,
but good \Cpp\ compilers weren't widely available, especially on the Cray
supercomputers on which I intended to work.  One can, of course, easily
\&{typedef} a C~structure that duplicates \Fortran's layout of a complex
number, but short of function calls one can't in~C perform arithmetic on
complex structures in the natural way one does in \Fortran.  Readability
was important.  So was vectorization, which also wasn't available in the
C~compilers available at that time and in any case would probably be broken
by function calls.  So reluctantly I decided that the
innermost, computational routines of the code should be written in
\Fortran.  

Of course, no way was \CWEB\ going to handle \Fortran\ code gracefully.
But my colleague Henry Greenside
^^{Greenside, Henry}
had been arguing strongly for the use of
\Ratfor\ as a superior tool, given that one was stuck with some sort of
\Fortran.  I agreed, and also hoped that \Ratfor's C-like syntax would be
close enough to C's that \CWEB\ would be adequate.  And so I plunged ahead,
writing in a mixture of~C and \Ratfor.

\CWEB\ worked for \Ratfor---sort of.  One was able to obtain the invaluable
index, and often the \Ratfor\ routines typeset just fine.
But there were constant annoying
glitches because of the inevitable differences of syntax.  After a few
years of experience, it became clear that one really wanted a proper
\Fortran\ version of \WEB.   Also, the
absence of a \Fortran\ macro preprocessor was causing us major annoyance.
Although Knuth's original \WEB\ had a rudimentary preprocessor, Levy had
deleted it for \CWEB, since C~has its own preprocessor.  
I decided there needed to be one built in that would serve all languages
equally well.  Thus, the major design goals were clear:  a new \Fortran\
\WEB\ that also supported \Ratfor\ and~C, with a macro preprocessor. 
So I learned how Knuth and Levy had implemented
the syntax production rules, sat down with a \Fortran\ reference manual,
and began to write some \Fortran\ productions.  I thought this would take a
couple of weeks.  That was actually about right. Ultimately, however, my
estimate of the total amount of
work involved in realizing all of my ideas about an ``industrial strength''
\WEB\ easily usable in the scientific environment was off by
at least two orders of magnitude. (Well, I'm a \It{theoretical} physicist.)

Some years later, I'm still upgrading \FWEB.  Had I been left to my own
devices, I probably would never have made it publicly available, since the
conflicts between trying to complete the research I had
intended to do and maintaining a reasonable robust code are almost
overwhelming.  But my colleague Charles Karney,
^^{Karney, Charles}
a true expert both in \TeX\
and scientific computation, began distributing codes written in \FWEB\ and
convinced me that a public announcement was the best way of both achieving
some sort of standardization and accomplishing the debugging task.  So an
announcement was timidly made, and the response has been amazing.  Most
incredible has been the continuing patience of the many users who are faced
with a utility that is still not bug-free and that they might have
designed differently.  \FWEB\ is far from perfect, but it's much better
than my original attempt because of the many well-thought-out suggestions
and questions that I continue to receive.  My profound thanks.

(Incidently, in the midst of all this a workable version of the \.{DIA}
code was finally finished with the completion of John Bowman's Ph.D.
thesis\cite{Bowman} 
^^{Bowman, John}
at Princeton University.  To John fell the terrible task of working with
the early prototypes of \FWEB.
The demands of his project stressed the system to its limits, sometimes
beyond, and elaborate kludges were sometimes necessary in order for him to
continue in a timely way with his research.  But John's excellent, properly
skeptical remarks also measurable improved \FWEB, and in the final analysis
it's still not clear to me that we could have accomplished so much in a
period of just a few years had we not had the principles of \WEB\ and
literate programming to help and guide us.  So I'll both apologize to John
for the early days as well as thank him for his patience and valuable
suggestions.  Although it's not uncommon for recent Ph.D.'s to want never
to think about the thesis research again, I hope John will be an exception,
since his contributions to both physics and \FWEB\ have been outstanding.

\subsection Why is this {\tt *!@\%*\#@!} manual so large?.

As stated above, \FWEB\ evolved from the excellent, tidy \CWEB\ code of
Levy and Knuth.  Without \CWEB\ and Knuth's original \WEB, there would be
no \FWEB, so my debt to those authors is very large indeed.  So I attempted
to retain the original manual that came with \CWEB, adding to it as
necessary.  That worked in the beginning, but as various features were
added and, in particular, as I continued to try to explain \WEB\
programming to a scientific user community that was strongly oriented
toward vanilla \Fortran, the manual accreted very much new material---too
much for the present organization.

From at least two points of view, it is time for a complete rewriting of
the manual.  First, the appearance of Knuth's new book\cite{Knuth} on {\sl
Literate Programming} means that much background material can be omitted
from the manual.  Second, I'm probably past the experimental stage of
\FWEB; the functional design has mostly stabilized and I've accumulated
enough experience to know where the troublesome points are.  So there's
just the issue of time to worry about.  Unfortunately, that's nontrivial,
so for now one is stuck with the present monstrosity.

However, the size and detail of this manual are alleviated in two ways.
First, Marcus Speh\cite{Speh}
^^{Speh, Marcus}
moderates an \FWEB\ literate programming question and 
answer bulletin board and information service, from which elementary
information can be easily obtained.  Second, some of the appendices to this
manual can be printed separately as a self-contained user guide.  Third,
\.{emacs} users can obtain online help from an \.{fweb.info} file that is
distributed with the \FWEB\ release.

\section The PHILOSOPHY of \WEB.[2.6] ^^(\>{WEB}!philosophy(

\parinserto{1}{5}{0.55}
``The {\ssbf WEB} system consists of two processors,
{\ssbf WEAVE} and {\ssbf TANGLE}.  These are {\bfit software tools}...''

The \WEB\ system consists of two processors, \WEAVE\ and \TANGLE. 
^^[\>{WEAVE}] ^^[\>{TANGLE}]
These are \It{^:software tools:} in the sense of \KP\cite{KP}.
^^{Kernighan, B.} ^^{Plauger, P.}
Together, these processors make important
contributions to the two principle facets of software design: how to
efficiently write a program that works and that can be easily maintained
(\TANGLE); and how to document what you have done so that both you and
others can understand, appreciate, and later modify the code (\WEAVE).

\subsection The purpose of the processors. ^^(TeX:\TEX!need for(

If one is not interested in obtaining documentation, the \TANGLE\ processor
can be used stand-alone, as a powerful preprocessor for any of the source
languages.  The \WEAVE\ processor must be used in conjunction with \TeX\ in
order to obtain the documentation. Here documentation refers both to prose
exposition of the logic and algorithms of the code, as well as to a typeset
listing of the code itself.  Note that, strictly speaking, you don't
actually have to know \TeX\ in order to document your code with \WEAVE.
Just typing straight text at the appropriate places will produce
documentation whose quality will be far in excess of what can be achieved
with comment lines embedded in the source code. The code itself is typeset
automatically in a visually appealing format by using special \TeX\ macros
about which the user need not generally be concerned.  However, the more
features of \TeX\ you employ, ^^{features!employing \TEX}
the higher quality your documentation will
be.  This is particularly important when the algorithms you are explaining
are based on complicated mathematical formulas. The ability to typeset
intricate mathematics right next to the code that implements the algorithm
(or even as a comment \It{within} a line of source code), instead of trying
to spell out the symbols in words in a series of comment lines, is so
extraordinarily useful that it becomes difficult to understand how one
could ever have gotten along without it.  Compare, for example, the
standard Fortran commenting style

{\codemode
C Perform the integral over v parallel from alpha to beta of the Maxwellian:
\Tab call integrate(x,alpha,beta,fM)
}
\noindent with what \FWEAVE\ can achieve:
{
\WP\7
\&{call} $\\{integrate}(\|x,\alpha,\beta,f_M)$\5
\Wc{ Perform $\int_{\alpha}^{\beta}\!dv_\parallel\,f_{\rm M}(v_\parallel).$ }

}
\noindent Here one needs to know something about \TeX\ (not very much) in
order to use math mode in the text of the comment; however, the typesetting
of the equation itself was performed automatically. (If you want to know
precisely how this was done, read about ``Overloading identifiers'' below.)
Time spent learning the fundamentals of
\TeX\ will be amply repaid in dramatically increased ^{productivity}---and
it's not hard to learn to do even rather powerful operations.

^^)TeX:\TEX!need for)

\subsection Top-down programming and structured design.

\parinserto{2}{6}{0.6}
``The fundamental logic of the {\ssbf WEB} system encourages `top-down'
programming and `structured' design.''

The fundamental logic of the \WEB\ system encourages ``top-down''
programming and ``structured'' design. 
^^:design, structured: ^^:programming!top-down: 
Quoting from \KP, ``Top-down design
and successive refinement attack a programming task by specifying it in the
most general terms, then expanding these into more and more specific and
detailed actions, until the whole program is complete.  Structured design
is the process of controlling the overall design of a system or program so
the pieces fit together neatly, yet remain sufficiently decoupled that they
may be independently modified. \dots\ Each of these disciplines can
materially improve programmer productivity and the quality of code
produced.'' The \WEB\ system encourages you to work top-down by giving you
the ability
to break up your code into independent segments (called ``\It{^{modules}}'').
Often, modules correspond to individual subroutines.  However, this is not
necessary and the \WEB\ system goes further by strongly encouraging you to
also subdivide long subroutines into additional modules that can be given
names for readability, put into a separate place, and explained as logic
dictates. \WEAVE\ prints out your explanations (and associated code
fragments) in the \It{logical} order in which you have decided to explain
the code.
\TANGLE\ strips off the explanations and rearranges the code into the
\It{physical} order in which the compiler should see it. For example, in
\Fortran\ all \&{common} declarations ^^{declarations!\<{common}}
must physically be placed at the beginning of a subroutine, before
executable code. However, various parts of such declarations may be quite
unrelated, and should logically be explained in separate, not necessarily
adjacent, sections of the documentation. As another example, in C~code
function prototypes should appear at the beginning if they are to be
useful; however, it's distracting to find a very long list of prototypes at
the beginning of the documentation.  \WEB\ allows one to both place
the prototypes at the end of the documentation and to tell the compiler to
read them first.  Finally, it might be desirable to explain the output
routines of a code before the input routines, since one might then better
know exactly what should be input.

Though top-down programming is easy with \WEB, bottom-up coding is not
excluded either.  It's perfectly possible to write very low-level routines
first, if that's convenient, and hook them into the web. The flexibility to
mix top-down and bottom-up programming in a superior documentation
environment means that one gets the best of all possible worlds!

\comment 
{\ninerm
The process is
something like pigeon-holing mail, or filing records in a banking system.
Assume that the bank must eventually process all the records for a certain
month by customer number, and assume that as the data comes into the bank
(with transactions of various customers randomly interspersed)
it will be alphabetized by customer name in order of receipt. The
alphabetical order and the numerical order of the records need not be the
same.  We shall equate ``customer name'' with ``module name,''
``order of receipt'' with ``logical order'' (order of receipt of ideas),
and ``numerical order'' with ``physical order.''  Filing the records into the
appropriate  
customer bins (modules) is the function of (the phase-one pass of) the
\WEB\ system. After all records have been properly filed, a second phase
processes them.  Phase two of \TANGLE\ processes each bin in  ascending
numerical order. Phase two of \WEAVE\ prints a summary of all transactions
of all customers, identified in the output by both name and number,
\It{in the order that they were originally received}. (The customer might
desire a printout of just his bin, but this microscopic view is not what
\WEAVE\ provides directly. Rather, \WEAVE\ provides a \It{macroscopic}
perspective of all the transactions so the bank can see when and how they
all fit together.)  For good measure, phase three of \WEAVE\ produces a
complete index and cross-reference of all the transactions [so that, in
fact, the transactions of a particular customer (module) can be readily
identified].

}
\endcomment

Although \WEB\ is simple in conception, it is quite sophisticated in
practice because \WEAVE\ uses the full power of \TeX\ to typeset not only
the expository documentation but also the actual code.  (Note that
automatically formatting source code is nontrivial, because
\WEAVE\ must understand a good deal about the language syntax in order to
emphasize keywords, indent loops, and so forth.)  Such visual enhancements
help one to write good code, because it can be
more clearly and logically explained and, therefore, better understood in
the future. 

\parinsert{4}{7}{0.65}
{``When arbitrary choices of syntax have arisen, the design of \FWEB\ has
been strongly influenced by the solution adopted by the ANSI standard
for~C.''}

Furthermore, the \FWEB\ version of the \WEB\ system goes significantly
beyond this. In 
fact, \FTANGLE\ is also a \It{macro preprocessor} ^^{macro!preprocessing}
and a \It{statement translator}. ^^{statement!translation}
By allowing symbolic macro abbreviations for commonly used
constructions, \FTANGLE\ allows you to write significantly more concise and
therefore more readable code. Furthermore, in its \Ratfor\ mode
^^{Ratfor:\RATFOR} 
it endows
the \Fortran\ language with a richer, C-like syntax that provides much more
logical, flexible, and readable loop and conditional constructions. These
constructions are translated directly into
\Fortran\  code. Although it is impossible to fully correct for the many
design deficiencies of \Fortran\ (except by writing in a better language
such as~C, which is highly recommended whenever possible), in many
situations the 
\Ratfor\  syntax is so close to that of the C~language that users have
complained that they can't remember in which language they're programming.
\FWEB\ deliberately adopts the point of
view that the language syntaxes should be as close as possible because it
is a common practice to mix languages, and uniform syntax should reduce the
frequency of errors.  When arbitrary choices of syntax have arisen, the
design of
\FWEB\  has been strongly influenced by the solution adopted by
the recent ANSI standard for~C. ^^{language!C!ANSI standard for}
For example, the macro preprocessor behaves like C's, not like \.{m4} or
Knuth's original preprocessor for his Pascal \WEB.

\subsection Knuth's original description of \WEB.

We begin with Knuth's original description of \WEB.

\KNUTH
``The ^[philosophy] behind \.{WEB} is
that an experienced system programmer, who wants to provide the best
possible documentation of his or her software products, needs two things
simultaneously:  a language like \TeX\ for formatting, 
^^{language!formatting} ^^{language!TeX:\TEX}
and a language like~\[\C\]\  for programming.
^^{language!programming} ^^{language!C}
Neither type of language can provide the best
documentation by itself; but when both are appropriately combined, we
obtain a system that is much more useful than either language separately.

``The structure of a software program ^^{software program!structure of}
may be thought of as a ``^:web:'' that
is made up of many interconnected pieces. To document such a program, we
want to explain each individual part of the web and how it relates to its
neighbors. The typographic tools provided by \TeX\ give us an opportunity
to explain the local structure of each part by making that structure
visible, and the programming tools provided by \[languages such as~\C\ or
\Fortran\]  make it possible for us to specify the algorithms formally and
unambiguously. By combining the two, we can develop a style of programming
that maximizes our ability to perceive the structure of a complex piece of
software, and at the same time the documented programs can be mechanically
translated into a working software system that matches the documentation.

\parinsert{5}{7}{0.5}
``The structure of a software program may be thought of as a `web' that
is made up of many interconnected pieces.''

``Since \.{WEB} is an experimental system developed for internal use within
the \TeX\ project at Stanford, this report is rather terse, and it assumes
that the reader is an experienced programmer who is highly motivated to
read a detailed description of \.{WEB}'s rules. Furthermore, even if a less
terse manual were to be written, the reader would have to be warned in
advance that \.{WEB} is not for beginners and it never will be: The user of
\.{WEB} must be familiar with both \TeX\ and \[the source language in which
he is writing\]. When one writes a \.{WEB} description of a software
system, it is possible to make mistakes by breaking the rules of \.{WEB}
and/or the rules of \TeX\ and/or the rules of \[the source language\].
^^{rules!breaking the}
In practice, all three types of errors will occur, and you will get different
error messages from the different language processors. In compensation for
the sophisticated expertise needed to cope with such a variety of
languages, however, experience has shown that reliable software can be
created quite rapidly by working entirely in
\.{WEB} from the beginning; and the documentation of such programs seems
to be better than the documentation obtained by any other known method.
Thus, \.{WEB} users need to be highly qualified, but they can get some
satisfaction and perhaps even a special feeling of accomplishment when
they have successfully created a software system with this method.''
\endKnuth

\subsection How to use \WEB.

\Knuth ^^[\>{WEB}!using]
\parinserto{3}{4}{0.55}
Extensive cross-index information is gathered automatically.

To use \.{WEB}, you prepare a file called \.{COB.WEB} (say), and then you
apply a system program called \.{WEAVE} to this file, obtaining an output
file called \.{COB.TEX}.  When \TeX\ processes \.{COB.TEX}, your output
will be a ``pretty printed'' version of \.{COB.WEB} that takes appropriate
care of typographic details like page layout and the use of indentation,
italics, boldface, etc.; this output will contain extensive cross-index
information that is gathered automatically. You can also submit the same
file \.{COB.WEB} to another system program called \.{TANGLE}, which will
produce \[for example\], a file \.{COB.FOR} that contains the \Fortran\ code
of your \.{COB} program. The \Fortran\ compiler will convert \.{COB.FOR}
into machine-language instructions corresponding to the algorithms that
were so nicely formatted by \.{WEAVE} and \TeX. Finally, you can (and
should) delete the files \.{COB.TEX} and \.{COB.FOR}, because \.{COB.WEB}
contains the definitive source code. \[{\bf Are you paying attention? Did
you hear what I just said?}\] Examples of the behavior of \.{WEAVE} and
\.{TANGLE} are appended to this manual.
\endKnuth

When you are using \FWEB\ you should use the commands
\.{FWEAVE} and \.{FTANGLE}
^^{\>{FWEAVE}} ^^{\>{FTANGLE}} ^^{\>{FWEB}!using}
to avoid confusion with the original Pascal
\WEB\ processors \WEAVE\ and \TANGLE, which are still supplied with the
\TeX\ distribution. 

Let us review what has been said so far. Given a \Fortran\ code that has
been prepared in the \WEB\ format in file \.{test.web}, to get compilable
code you say (using upper case solely for emphasis to distinguish the
system command from the file name)

{\codemode
\FTANGLE\ test
}

\noindent This produces the file \.{test.for}, which can be compiled,
linked, and executed. To get the documentation of your code, you say

{\codemode
\FWEAVE\ test
}

\noindent This produces the file \.{test.tex}, which can be processed with
either Plain \TeX\ or \LaTeX.

A worry that arises when one is deciding whether to use the \WEB\ system is
whether the ^{overhead} ^^{\>{WEB}!using!overhead of}
of using it will be annoying. Experience shows that
the answer is generally ``No''. The \TANGLE\ processor is quite fast;
the pass through \TANGLE\ typically takes a small fraction of the time to
compile and link, especially for large codes. \WEAVE\ is slower (it does a
\It{lot} of work!), and furthermore one must run the output of \WEAVE\
through \TeX. However, when one is developing a code he typically tangles
it many times for each time he weaves it, and furthermore the clarity and
completeness of the resulting documentation are very much worth any
additional overhead. The shift from heavily time-shared mainframes to very
fast, individual workstations will further reduce any annoyance with overhead.

\Knuth ^^[\>{WEB}!enhancements]
\parinsert{3}{8}{0.6}
``{\ssbf FWEB} enhances the source languages by providing a relatively
sophisticated, C-like macro capability together with the ability to
permute pieces of the program text...''

Besides providing a documentation tool, \FWEB\ enhances the source
languages by providing a \[relatively sophisticated, \C-like\] macro
capability ^^{macro!processing}
together with the ability to permute pieces of the program text,
so that a large system can be understood entirely in terms of small ^{modules}
and their local interrelationships. \[Furthermore, it can even understand
syntactical constructions absent from the source language and translate
those into valid, compilable code; for example, it can translate the
\Ratfor\ dialect of \Fortran\ directly into standard \Fortran.\]
^^{statement!translation} 
The \.{TANGLE} program is so named ^^{\>{TANGLE}!name justified}
because it takes a given ^{web} and moves the
modules from their web structure into the order required by \[the
compilers\]; the advantage of programming in \.{WEB} ^^{\>{WEB}!advantages of}
is that the algorithms
can be expressed in ``untangled'' form, with each module explained
separately.  The \.{WEAVE} program is so named ^^{\>{WEAVE}!name justified}
because it takes a given web
and intertwines the \TeX\ and \[code\] portions contained in each module,
then it knits the whole fabric into a structured document.  (Get it? Wow.)
Perhaps there is some deep connection here with the fact that the German
word for ``weave'' is ``{\it web\/}'', and the corresponding Latin
imperative is ``{\it texe\/}''!
\endKnuth

\subsection History and design influences (Knuth).

\KNUTH
{\ninerm ^^(\>{WEB}!history of( ^^(references!literature(
It is impossible to list all of the related work that has influenced the
design of \.{WEB}, but the key contributions should be mentioned
here.\quad (1)~Myrtle Kellington, as executive editor for ACM
publications, developed excellent typographic standards for the
typesetting of Algol programs during the 1960s, based on the original
designs of Peter Naur; the subtlety and quality of this influential work
can be appreciated only by people who have seen what happens when other
printers try to typeset Algol without the advice of ACM's copy
editors.\quad(2)~Bill McKeeman introduced a program intended to automate
some of this task [Algorithm 268, ``Algol~60 reference language editor,''
{\sl CACM \bf8} (1965), 667--668]; and a considerable flowering of such
programs has occurred in recent years [see especially Derek Oppen,
``Prettyprinting,'' {\sl ACM TOPLAS \bf2} (1980), 465--483; G.~A. Rose and
J. Welsh, ``Formatted programming languages,'' {\sl SOFTWARE Practice
\char`\&\ Exper.\ \bf11} (1981), 651--669].\quad(3)~The top-down style of
exposition encouraged by \.{WEB} was of course chiefly influenced by Edsger
Dijkstra's essays on structured programming in the late 1960s. The less
well known work of Pierre-Arnoul de Marneffe [``Holon programming: A
survey,'' Univ.\ de Liege, Service Informatique, Liege, Belgium, 1973; 135
pp.\null] also had a significant influence on the author as \.{WEB} was
being formulated.\quad(4)~Edwin Towster has proposed a similar style of
documentation in which the programmer is supposed to specify the relevant
data structure environment in the name of each submodule [``A convention
for explicit declaration of environments and top-down refinement of
data,'' {\sl IEEE Trans.\ on Software Eng.\ \bf SE--5} (1979), 374--386];
this requirement seems to make the documentation a bit too verbose,
although experience with \.{WEB} has shown that any unusual control
structure or data structure should definitely be incorporated into the
module names on psychological grounds.\quad(5)~Discussions with Luis
Trabb~Pardo in the spring of 1979 were extremely helpful for setting up a
prototype version of \.{WEB} that was called \.{DOC}.\quad (6)~Ignacio
Zabala's extensive experience with \.{DOC}, in which he created a full
implementation of \TeX\ in \PASCAL\ that was successfully transported to
many different computers, was of immense value while \.{WEB} was taking
its present form.\quad(7)~David~R. Fuchs made several crucial suggestions
about how to make \.{WEB} more portable; he and Arthur~L. Samuel
coordinated the initial installations of \.{WEB} on dozens of computer
systems, making changes to the code so that it would be acceptable to
a wide variety of \PASCAL\ compilers.\quad(8)~The name \.{WEB} itself
was chosen in honor of [Knuth's] wife's mother, Wilda Ernestine Bates.
^^{mother-in-law} ^^{Bates, Wilda E.}

}
\endKnuth ^^)\>{WEB}!history of) ^^)references!literature)

\Knuth
The appendices to this report contain \[various examples of \WEB\
programming\].  Complete \.{WEB} programs for the
\.{FWEAVE} and \.{FTANGLE} processors \[are available in the source files
provided with the release of \FWEB\]. A study of these examples, together
with an attempt to write \.{WEB} programs by yourself, is the best way
to understand why \.{WEB} has come to be like it is.
\endKnuth
^^)\>{WEB}!philosophy)

\section SIMPLE EXAMPLES. 

Before we plunge into the depths of the \WEB\ system, it may be useful to
introduce several simple examples, even though few of the concepts have
been yet introduced. 

\subsection A simple C program organized with {\tt FWEB}. ^^(example!C program(

The first example gives the outline of a simple C~program
that has 
been organized with \FWEB. (If you are not familiar with~C, you should not
worry. Examples from both \Fortran\ and \Ratfor\ will be given shortly, and
almost all of the important \WEB\ features are language-independent.)
First, we present a verbatim listing of the source code.  Then, we show how
\FWEAVE\ typesets the documentation.  
\HRULE
\verbatim{demo0.web}
\HRULE
It is hoped that this example is mostly self-explanatory. Its
various facets will be explained in great detail below. Here, we just
observe that the source file is broken up into \It{modules} or
\It{sections}, ^^<section> ^^<module>
which in turn 
are divided into parts, with the aid of simple commands or \It{^:control
codes:} beginning with~\atcmd{}. In each section there is space for \TeX'd
documentation, 
^^<documentation!\TEX>
macro definitions ^^<macro!definition>
(and other stuff to be explained later),
and the code itself. The code can be broken up into named
fragments, and these can be defined elsewhere. Therefore, each section can
be short and its purpose and logical structure can be easily captured by
the eye.  The other nuances of this example will be explained later.

\FWEAVE\ typesets this example as follows.  (For brevity, the last few
pages of the output from \FWEAVE\ are omitted here; those include the index
and the table of contents.  Those items are some of the most important
features of the \WEB\ system.  To see how they appear for this example, you
can run \FWEAVE\ yourself on the source code for this demo, which is called
\.{demo0.web}.) 
\HRULE
\typeset{demo0}
\HRULE
Note how module numbers are used both in module names and as subscripts to
identifiers to help one find his way around the documentation.  (When an
identifier is used in the same section in which it is defined, it is
subscripted with a bullet.)  These features will be discussed at length
later.

^^)example!C program)

\subsection Converting a \Fortran\ program to {\tt WEB}.
^^(example!\Fortran\ program(

We continue to ``learn by doing'' by considering how to convert a very
simple \Fortran\ code to \WEB.  Consider the following elementary example:
\filbreak
\HRULE
\verbatim{f0to_web.src}
\HRULE
The code consists of one main program and several related subroutines.  To
convert such a code to \WEB, the standard procedure is to 
make each program unit a separate \WEB\ section.  This is done by prefacing
each program unit by (1)~an \atcmd{*} or \atcmd{\ }~command, signifying
major or minor sections, respectively; (2)~explanatory
\TeX\ text about the purpose and general logic of the program unit, and
(3)~an \atcmd{a}~command to signal the start of the actual code.  Since the
explanatory text can be absent, the quickest way of converting a \Fortran\
code is to preface each subroutine with~\atcmd{\ @a}.  (Actually, one could
just preface the entire code with~\atcmd{\ @a}, thereby making the entire
code into just one huge section.  It would still weave and
tangle correctly.  However, in this case one loses one of the most
important feature of \WEB---namely, a useful index.  With everything in one
big section, every index entry would refer to section~1!)  Thus, the \WEB\
code one constructs from the present \Fortran\ source will look something
like this:
\HRULE
\verbatim{f0to_web.web}
\HRULE
Notice that in the conversion we removed the comments that preceded the
beginning of the program units.  Such comments are best incorporated into
the names of major sections or expanded into a more leisurely prose that
becomes the \TeX\ text.  However, we left a comment internal to the main
program (almost) intact.  However, we took the opportunity to change the
word ``\.{alpha}'' into the more meaningful \TeX\ form ``\.{\$\\alpha\$}''.
This is not necessary when one is making a first cut at converting a
working code, but in the long run it greatly improves the readability.
Thus, the present example weaves to
\HRULE
\typeset{f0to_web}
\HRULE
\filbreak
This leads us to a very important point:  \WEAVE\ does not just
transcribe the contents of comments literally, it treats them as \TeX\ to
be typeset.  Thus, if your comments weren't written with \TeX\ in mind but
contain characters that are special to
\TeX, such as~'\.{\$}' or~'\.{\_}', \TeX\ may complain or typeset the
comments in weird ways.  Users converting large codes may find this quite
annoying.  However, note the annoyance should not arise when writing a code
in \WEB\ from 
the start since one should be thinking about and writing in \TeX\ from the
very beginning.

A related point is that authors of pre-\WEB\ codes have sometimes gone to
considerable lengths to align fields within comments in readable,
meaningful ways.  For example, one might see something like this in a
\Fortran\ code:

\begintt
C The method is as follows:
C    (1) Specify the initial condition.
C    (2) Integrate forward one step.
\endtt

\noindent Unfortunately, by default \WEAVE\ will undo most of this
painstaking work.  Unless one does something special, the previous comments
will come out looking something like this:

\WC{ The method is as follows:  (1) Specify the initial
condition.  (2) Integrate forward one step.}  

\noindent The pretty alignment has been
totally lost!  This is the price one pays for having the full power of
\TeX\ available.  In \TeX, one has the powerful \.{\\halign} macro and
other mechanisms to
create alignments.  Had one been writing in \WEB\ from the beginning, he
would have used that naturally.  The best advice, then, is:  Write all your
codes in \WEB\ from the very beginning.  It's easier to do that than to
convert them later---and the results are generally spectacular.

Actually, there is a mechanism that will transcribe arbitrary material verbatim
to the output.  This is the \It{meta-comment}:  ^^:comment!meta-:
Any material enclosed
between the commands~\atcmd{(} and~\atcmd{)} ^^{\>{@(}} ^^{\>{@)}}
(each of which should begin in
column~1 and be on a line by itself) will be appropriately enclosed
in a verbatim environment (slightly different depending on whether \TeX\ or
\LaTeX\ is used).  Thus, spaces and alignment are preserved in the
following example:

\vbox{
{\codemode
@(
0\ 2\ 4
\ 1\ 3\ 5
@)
}
}

The meta-comment can be used for purposes other than comments;  see the
more detailed discussion of the \atcmd{(}~command below.  In general,
it is not recommended that one use meta-comments in lieu of
standard \WEB\ comments whose contents are valid \TeX.  

^^)example!\Fortran\ program)

In Appendices~\hbox{A--E} we describe more complicated instances of \WEB\
programming.  Many further examples can be found throughout the text.  As
we proceed, we will learn more methods and guidelines for writing or
converting to high-quality \WEB\ code.  A more complete review of the
typical conversion procedure will be given later in the section ``Usage
Tips and Suggestions'' below

\section GENERAL RULES.[4.14] ^^(rules!syntax(

In this section we describe the syntax rules ^^[syntax rules!\WEB]
 that must be followed in
preparing a \WEB\ source file. Although the syntax is ultimately
straightforward, the issue itself is somewhat complex because of the need
to simultaneously process source codes written in several different
languages. We shall therefore proceed in stages, first introducing the logic, 
later discussing nuances and differences between languages.

\subsection Text.

The original documentation for \WEB\ stated the following:
^^[\>{WEB}!source file!syntax of]

\KNUTH
``A \.{WEB} file is a long string of text that has been divided into
individual lines. The exact line boundaries are not terribly crucial, and a
programmer can pretty much chop up the \.{WEB} file in whatever way seems
to look best as the file is being edited; but string constants and control
texts must end on the same line on which they begin, since this convention
helps to keep errors from propagating.  The end of a line means the same
thing as a blank space.''
\endKnuth

\noindent Unfortunately, the situation becomes intrinsically more
complicated when one desires to support a column-oriented language such as
\Fortran--77.
^^{language!column-oriented} ^^{language!Fortran:\FORTRAN}
However, this detail can be dealt with later. For~C and \Ratfor\
free-form syntax is indeed appropriate, and once you've used it you'll
probably hate going back to \Fortran's clumsy conventions.  Note that
\Fortran--90 allows a free-form mode, which should be used for new codes.
(However, as we will explain below, \Ratfor--90 is still easier to use than
free-form \Fortran--90.)

\Knuth
\parinsert{3}{8}{0.6}
``Writing \WEB\ programs is something like writing \TeX\ documents, but with
an additional `code mode' that is added to \TeX's horizontal mode,
vertical mode, and math mode.''

Two kinds of material go into \.{WEB} files: \TeX\ text and \[code\] text.
^^{text!TeX:\TEX} ^^{text!code}
A programmer writing in \.{WEB} should be thinking both of the
documentation and of the \bdots\ program that he or she is creating;
i.e., the programmer should be instinctively aware of the different
actions that \.{WEAVE} and \.{TANGLE} will perform on the \.{WEB} file.
\TeX\ text is essentially copied without change by \.{WEAVE}, and it is
entirely deleted by \.{TANGLE}, since the \TeX\ text is ``pure
^{documentation}.'' \[Code\] text, on the other hand, is formatted by
\.{WEAVE} and it is shuffled around by \.{TANGLE}, according to rules that
will become clear later. For now the important point to keep in mind is
that there are two kinds of text. Writing \.{WEB} programs is something
like writing \TeX\ documents, but with an additional ``\[code\] mode''
^^:mode!code: ^^:code!mode:
that is added to \TeX's horizontal mode, vertical mode, and math mode.

\subsection Modules.

A \.{WEB} file is built up from units called {\sl modules\/} or {\sl
sections\/} that are more
or less self-contained.  Each \[section\] has three parts:

{\narrower
\yskip\item{1)} ^^:module!part!TeX\actual\TEX: ^^:part!TeX\actual\TEX:
	^^:TeX\actual\TEX!section: 
A \hl{\TeX\ part}, containing explanatory material about what
is going on in the module.

\item{2)} ^^:module!part!definition: ^^:definition!part: ^^:part!definition:
A \hl{definition part}, containing (1)~macro definitions that
serve as abbreviations for \[code\] constructions that would be less
comprehensible if written out in full each time, \[(2)~preprocessor
commands that allow one to selectively process the macro definitions,
(3)~format statements that tell \WEAVE\ how to deal with identifiers such
as macro names that are not in its vocabulary, and (4)~miscellaneous
commands related to operator overloading, limbo text, etc.; these will be
explained later.\]

\item{3)} ^^:module!part!code: ^^:part!code:
A \hl{\[code\] part}, containing a piece of the program that
\.{TANGLE} will produce. \It{This \bdots\ code should ideally be about a
dozen lines long, so that it is easily comprehensible as a unit and so that
its structure is readily perceived.} \[(Italics added.)\] \[Preprocessor
commands may also appear in the code part, allowing one to selectively include
or delete fragments of code.\]

}

\yskip\noindent ^^[parts, order of]
The three parts of each module must appear in this order;
i.e., the \TeX\ commentary ^^{commentary!TeX:\TeX}
must come first, then the definitions, and
finally the \[source\] code. Any of the parts may be empty.

\subsection Beginning a module. ^^{modules!beginning}

\parinserto{3}{4}{0.4}
A module begins with either `{\ssbf @}{\tt\ }' or `{\ssbf @*}'.

A ^:module: begins with the pair of symbols~\atcmd{\ } or~\atcmd{*}, 
^^{\>{@\ }} ^^{\>{@*}}
where
`\.{\ }'~denotes a blank space. A module ends  ^^[module!end of]
at the beginning of the next
module (i.e., at the next~\atcmd{\ } or~\atcmd{*}), or at the end of the
file, whichever comes first.  The \.{WEB} file may also contain material
that is not part of any module at all, namely the text (if any) that occurs
before the first module.  Such text is said to be ``in limbo''; 
^^:limbo!in: ^^:limbo!section: 
it is ignored by
\.{TANGLE} \[except for any embedded language-switching commands\] and copied
essentially verbatim by \.{WEAVE}, so its function is \[primarily\]
to provide any additional formatting instructions that may be desired in
the \TeX\ output. Indeed, it is customary to begin a \.{WEB} file with
\TeX\ code in limbo that loads special fonts, defines special macros,
changes the page sizes, and/or produces a title page. \[You should also
place a global language command ^^{language!global}
such as~\atcmd{n} somewhere in limbo; see below.\]
\endKnuth

If a source file begins with~\atcmd{z} as the \It{very first} two characters, 
^^{\>{@z}} ^^{\>{@x}}
all text between the~\atcmd{z} and
the end of a subsequent line begun with~\atcmd{x} is completely ignored by
both processors.  This material is intended to include commentary 
^^:commentary!invisible:
such as author, date, version, etc.  See the demo programs scattered
throughout this manual for simple examples of such commentary.

\Knuth
^^[module!number of] ^^[module!references]
Modules are numbered consecutively, starting with~1; these numbers appear
at the beginning of each module of the \TeX\ documentation, and they appear
as bracketed comments at the beginning of the code generated by that module
in the \[source\] program.

Fortunately, you never mention these numbers yourself when you are writing
in \.{WEB}. You just say~\atcmd{\ } or~\atcmd{*} at the beginning of each new
module, and the numbers are supplied automatically by \.{WEAVE} and
\.{TANGLE}. As far as you are concerned, a module has a
name instead of a number;
^^:module!name: ^^{\>{@<}} ^^{\>{@>}} ^^{\>{@<...@>}}
such a name is specified by writing \atcmd{<}
followed by \TeX\ text followed by \atcmd{>}---for example, `\.{@<Read
\$\\alpha\$ and\~\$\\beta\$@>}'.  When \.{WEAVE} outputs a module name, it
replaces the~\atcmd{<} and~\atcmd{>} by angle brackets and inserts the module
number in small type---for example, `\WX5:Read $\alpha$ and~$\beta$\X \X'.
Thus, when you read the output of \.{WEAVE} it is 
easy to locate any module that is referred to in another module.

For expository purposes, a module name should be a good description of the
contents of that module, i.e., it should stand for the abstraction
represented by the module; then the module can be ``plugged into'' one or
more other modules so that the unimportant details of its inner workings
are suppressed.  A module name therefore ought to be long enough to convey
the necessary meaning. Unfortunately, however, it is laborious to type
such long names over and over again, and it is also difficult to specify a
long name twice in exactly the same way so that \.{WEAVE} and \.{TANGLE}
will be able to match the names to the modules. Therefore a module name
can be abbreviated ^^{module!name!abbreviating} ^^{module
names!abbreviations for} ^^{\>{...} "(ellipsis")} 
^^{ellipsis "(\noexpand\dots")} 
after its first appearance in the \.{WEB} file, by
typing \atcmd{<$\alpha$...@>}, where $\alpha$ is any string that is a prefix of
exactly one module name that appears in the file. For example, \atcmd{<Clear
the arrays@>} can be abbreviated to \atcmd{<Clear...@>} if no other module
name begins with the five letters `\.{Clear}'. Module names must otherwise
match character for character, except that consecutive blank spaces and/or
tab marks are treated as equivalent to single spaces, and such spaces are
deleted at the beginning and end of the name. Thus, \atcmd{< Clear { }the
arrays @>} will also match the name in the previous example.

We have said that a module begins with~\atcmd{\ } or~\atcmd{*}, but we didn't
say how it gets divided up into a \TeX\ part, a definition part, and a
\[code\] part.
\endKnuth

\subsection The definition part. ^^[module!part!definition] ^^[part!definition]

The \TeX\ part ends and
the definition part begins with the first appearance in the module
of one of a set of commands.  These are distinguished by the attribute that
they do not produce compilable code but rather tell one or the other
processor to do or remember something.  Those commands will be explained in
detail later; briefly, they are: 
^^{\>{@d}} ^^{\>{@f}} ^^{\>{@l}} ^^{\>{@m}} ^^{\>{@v}} ^^{preprocessing}
\clo{%
@d&Define an ``outer macro'' whose definition will be copied to the very
	beginning of the tangled output file.\cr
@f&Format an identifier to behave like some other identifier.\cr
@l&Specify \TeX\ text for \FWEAVE\ to output at the beginning of the
	limbo section.\cr
@m&Define an ``inner'' or ``\WEB\ macro'' to \FTANGLE.\cr
@v&Tell \FWEAVE\ how to ``overload'' an operator.\cr
@W&Tell \FWEAVE\ how to ``overload'' an identifier.\cr
@\#&Begin a \WEB\ preprocessing command such as~\.{@\#if}.\cr
}

\subsection The code part. ^^[module!part!code] ^^[part!code]

\Knuth ^^[\>{@<...@>=}]
\parinserto{3}{5}{0.40}
``The code part begins with the first appearance of `{\ssbf @a}' or `{\ssbf
@}{\tt<}'.''

The definition part ends and 
the code part begins with the first appearance of~\atcmd{a} or~\atcmd{<}. 
^^{\>{@a}} ^^{\>{@<}}
The latter option~\atcmd{<}
stands for the beginning of a module name, which is the name of the module
itself. An equals sign (\.=) must follow the \atcmd{>} at the end of this
module name; you are saying, in effect, that the module name stands for the
\[code\] text that follows, so you say `$\langle\,$module
name$\,\rangle=\null$code text'. Alternatively, if the \[code\] part begins
with~\atcmd{a} instead of a module name, the current module is said to be
{\sl unnamed}. Note that (generally) module names cannot appear in the
definition part 
of a module, because the first~\atcmd{<} in a module signals the beginning
of its \[code\] part. 
Any number of module names might appear in the \[code\] part, however, once
it has started.
\endKnuth

(Actually, in \FWEB\ module names \It{can} appear in the definition part in
certain circumstances. First, a module name may appear immediately after a
format command; see the discussion of~\atcmd{f} below.  Second, module names
may appear in \FWEB\ macro definitions if they are begun by~`\.{\#<}'
^^{\>{\PM<...@>}} 
instead of~\atcmd{<}; see the discussion of macros below.  Finally, module
names may appear inside of the vertical bars that signify a shift into code
mode.)

\subsection How {\tt TANGLE} makes compilable programs out of modules.

\Knuth ^^[\>{TANGLE}!general idea of]
\parinserto{7}{5}{0.5}
``There should be at least one unnamed module, otherwise there will be no
output.''

The general idea of \.{TANGLE} is to make a \[compilable\] program \[(or
programs, if one is mixing languages)\] out of these modules in the
following way: First all the \[code\] parts of unnamed modules
^^{module!unnamed}
are copied
down, in order; this constitutes the initial approximation~$T_0$ to the
text of the program. \It{(There should be at least one unnamed module,
otherwise there will be no output.)} Then all module names that appear in
the initial text~$T_0$ are replaced by the
\[code\] parts of the corresponding modules, and this substitution process
continues until no module names remain. Then all \[macros defined
by~\atcmd{m}\] are replaced by their equivalents, according to certain rules 
that are explained later. \[The resulting code may have pieces in any or
all of the several supported languages~C, \Cpp, \Fortran, \Ratfor, and~\TeX.
This code 
is run through an \It{output driver} appropriate for the language in
^^{output!driver} ^^{driver!output}
question; the driver writes files with the appropriate compiler
extension---`\.{.c}', `\.{.cpp}' (`\.{.c++}' for \Unix), `\.{.for}'
(`\.{.f}'~for \Unix), `\.{.rat}' (`\.{.r}' for 
\Unix), or~`\.{.x}'---and syntax. ^^{extensions!file-name}
^^{extensions!compiler} 
For example, 
the \Fortran--77 output driver ensures that statements begin in column~7 and
are correctly continued if they extend beyond column~72.\] All ^{comments}
will have been removed from
\[these programs\] except for the \[verbatim comments (either begun
explicitly by~\atcmd{/*} or~\atcmd{//} or implicitly selected by the
command-line option~\.{-v})
and the\] meta-comments delimited by~\atcmd{(} and~\atcmd{)}, as explained
below, and except for the module-number comments that point to the source
location where each piece of the program text originated in the \.{WEB}
file.

\parinsert{4}{8}{0.6}
``If the same name has been given to more than one module, the code text
for that name is obtained by putting together all of the code parts in
the corresponding modules.''

If the same name has been given to more than one module, the \[code\] text
for that name is obtained by putting together all of the \[code\] parts in
the corresponding modules. This feature is useful, for example, in a module
named `\.{Global variables}', since a C~programmer can then declare global
variables in whatever modules those variables are introduced, \[but be sure
that they will all be grouped together at the beginning of the code.  A
similar application arises in \Fortran\ when one is describing and defining
\&{common} declarations.\] When several modules have the same name,
\.{WEAVE} assigns the first module number as the number corresponding to
that name, and it inserts a note at the bottom of that module telling the
reader to `See also sections so-and-so'; this footnote gives the numbers of
all the other modules having the same name as the present one. The \[code\]
text corresponding to a module is usually formatted by \.{WEAVE} so that
the output has an equivalence sign in place of the equals sign in the
\.{WEB} file; i.e., the output says `$\langle\,$module
name$\,\rangle\equiv\null$code text'. However, in the case of the second
and subsequent appearances of a module with the same name, this `^{$\equiv$}'
sign is replaced by `^{$\mathrel+\equiv$}', as an indication that the \[code\]
text that follows is being appended to the
\[code\] text of another module.
\endKnuth

^^:section:
The previous paragraph is in Knuth's original words. Note that he uses
``module'' and ``section'' interchangably. A more precise distinction might
have been to use ``section'' for the distinct numbered entities that begin
with~\atcmd{\ } or~\atcmd{*}, and ``module'' for the concatenations of all
sections with the same names. Then one could say things like ``The unnamed
module consists of sections~1, 2, and~5.''  In any event, the user will
soon get used to how things work. In this article, we have generally chosen
to retain 
Knuth's original usage because it makes it easier to quote just what Knuth
said. 

\Levy: As \TANGLE\ starts and leaves modules, it writes down the line
number ^^{line!numbers}
of the original \WEB\ file. When the language is~C, this is done in
the form of the \C~preprocessor \&{\#line} command.
^^{\>{\PM line}}
This means that when
the compiler gives you error messages, or when you debug your program, the
messages refer to line numbers in the \WEB\ file, rather to ones in the
\C~file. In most cases, you can even forget about the \C~file altogether.
\[For other languages, the `\&{\#}' character is changed to a comment
character. Unfortunately, in \Fortran\ and \Ratfor\ there is no compiler
feature analogous to \&{\#line} that resets the line number, so for those
languages compiler error messages will refer to the output file, not the
\WEB\ file.\] 

\subsection How {\tt WEAVE} makes a \TeX\ file containing documention.

\Knuth ^^[\>{WEAVE}!general idea of]
The general idea of \.{WEAVE} is to make a \.{TEX} file from the \.{WEB}
file in the following way: The first line of the \.{TEX} file will
\[generally be output as\] `\.{\\input fwebmac.sty}'; 
^^:\>{fwebmac}!\>{.sty}:
this will cause \TeX\ to read in the macros that define \.{FWEB}'s
documentation 
conventions. \[(If you don't want this line to be first for some tricky
reason, turn it off with the command-line option
`\.{-w}'. ^^{\>{-w}}
However, you 
must then say yourself `\.{\\input fwebmac.sty}' somewhere in limbo.)\]  
\[Next may be inserted special \TeX\ material generated automatically by
the~\atcmd{l} or \atcmd{v}~commands; see below.\]
The
next lines of the file will be copied from whatever \TeX\ text is in limbo
^^{limbo!section}
before the first module.  Then comes the output for each module in turn,
possibly interspersed with end-of-page marks.  Finally, \.{WEAVE} will
generate a cross-reference ^{index} that lists each module number in which
each \[code\] identifier appears, and it will also generate an alphabetized
list of the module names, as well as a ^{table of contents} that shows the
page and module numbers for each ``starred'' module.

\subsection Starred (major) modules. ^^:module!starred:

What is a ``starred'' module, you ask?
A module that begins with~\atcmd{*} ^^[\>{@*}]
instead of~\atcmd{\ } is slightly special in that it denotes a new major
group of modules. The~\atcmd{*} should be followed by the title of this
group, followed by a period. Such modules will always start on a new page
in the \TeX\ output, and the group title will appear as a running headline
on all subsequent pages until the next starred module. The title will also
appear in the table of contents, and in boldface type at the beginning of
its module. Caution: Do not use \TeX\ control sequences in such titles,
unless you know that the \.{fwebmac} macros will do the right thing with
them. The reason is that these titles are converted to uppercase when they
appear as running heads, and they are converted to boldface when they
appear at the beginning of their modules, and they are also written out to
a table-of-contents file used for temporary storage while \TeX\ is working;
whatever control sequences you use must be meaningful in all three of these
modes.
\endKnuth

Starred sections
have associated level numbers, ^^:level!numbers: ^^:level!of starred section:
^^:subsection!level number of:
where 0~denotes the most significant level,
1~denotes a ^:subsection:, 2~denotes a subsubsection, and so on.  You can
indicate the level number in several ways.  First, if the command~\atcmd{*}
is not immediately followed by a digit, then the level is~0.
(This was the only possibility in the original \WEB\ design.)
Next, if \atcmd{*}~is followed by a positive digit, then that digit
indicates the level.  (Be default, that digit must be $\le 4$.)  Thus, you
can say 

{\codemode
@* MAJOR.  (The level is 0.)
@*3 Subsubsubsection.  (The level is 3.)
}
\noindent Note that entries are made in the table of contents for all starred
sections, including those whose level is greater than~0.

Level numbers are processed by \.{fwebmac} macros, not by code hard-wired
into \FWEAVE.  The level number is supplied as an argument to various
\.{fwebmac} macros, and one can redefine those macros to achieve various
special effects.  For example, entries in the table of contents are
formatted by the macro~\.{\\WZ} ^^{\CS{WZ}}
(which is defined inside the table-of-contents macro~\.{\\Wcon}), ^^{\CS{Wcon}}
whose first argument is the level number~$n$.  By default, the entry is just
indented by $n$~ems.  However, it is straightforward to achieve more
sophisticated effects (such as various fonts or case) by enhancing the
definition of~\.{\\WZ}  to include
an \.{\\ifcase} construction.  (See how this is done in \.{fwebman.tex} for
the table of contents for this manual.)
Similarly, by default major sections get a page break in the woven output,
whereas subsections do not; however, that can also be changed by redefining
the \.{fwebmac} macro \.{\\Wsectionbreak}. ^^{\CS{Wsectionbreak}}

\Knuth
The \TeX\ output produced by \.{WEAVE} for each module consists of the
following: First comes the module number (e.g., `\.{\\WM123.}' ^^{\CS{WM}}
at the
beginning of module 123, except that `\.{\\WN}' ^^{\CS{WN}}
appears in place of `\.{\\WM}' at the beginning of a starred module). Then
comes the \TeX\ part of the module, copied almost verbatim except as noted
below. Then comes the definition part and the \[code\] part, formatted
so that there will be a little extra space between them if both are
nonempty. The definition and \[code\] parts are obtained by inserting
a bunch of funny-looking \TeX\ macros into the \[source\] program; these
macros handle typographic details about fonts and proper math spacing,
as well as line breaks and indentation.
\endKnuth

(The original \WEB\ employed control sequences such as `\.{\\M}' instead of
`\.{\\WM}'. This makes the \.{tex}~file somewhat shorter and more readable
and makes the input 
phase of \TeX\ run a tiny bit faster. However, it seems undesirable to deny
the user most of the single-character upper-case control sequences; the
present \FWEB\ opts for user convenience.)

\Knuth ^^[\>{"|..."|}]
\subsection Code mode.

When you are typing \TeX\ text, you will probably want to make frequent
reference to variables and other quantities in your \bdots\ code, and you
will want those variables to have the same typographic treatment when they
appear in your text as when they appear in your program.  Therefore the
\.{WEB} language allows you to get the effect of \[source code\] editing
within \TeX\ text, if you place `\.|' marks before and after the \[code\]
material. For example, suppose you want to say something like this \[while
documenting \Fortran\ code\]:
\endKnuth
$$
        \hbox{The \&{integer} variable \\{itype} is used in such
statements as 
                $\&{if}(\\{itype}\WI\|m)\dots$} 
$$
The \TeX\ text would look like this in your \.{WEB} file:
$$\hbox{\.{The |integer| variable |itype| is used in such
statements as 
        |if(itype\ !=\ m)|\dots}}
$$

\noindent
Note that the \WEB\ file contained the construction `\.{!=}' instead of
\Fortran--77's standard (and archaic)~`\.{.ne.}'. In fact, you could have typed
either, but \WEB\ gives you the flexibility to type the more modern symbols
if you wish, thereby helping you to write clearer code. The options will be
explained in detail later; as much as possible, they follow the
conventions for~C.  Also, observe that either construction is
woven into the more meaningful symbol~`$\WI$'.

\Knuth
\bdots
Incidentally, the cross-reference index that \.{WEAVE} would make, in the
presence of documentation like this, would include the current module number as
one of the index entries for \\{itype}, even though \\{itype} might not
appear in the \[code\] part of this module. Thus, the index covers
references to identifiers in the explanatory comments as well as in the
program itself; you will soon learn to appreciate this feature. However,
the identifiers \&{integer},
\&{if}, and \|m would not be indexed,
because \.{WEAVE} does not make index entries for ^{reserved words} or
single-letter identifiers.
^^{identifiers!single-letter}
Such identifiers are felt to be so ubiquitous
that it would be pointless to mention every place where they occur.

\comment
Speaking of identifiers, the author of \.{WEB} thinks that
\\{IdentifiersSeveralWordsLong} look terribly ugly when they mix
uppercase and lowercase letters. He recommends that
\\{identifiers\_several\_words\_long} be written with underline characters
to get a much better effect. The actual identifiers sent to the \PASCAL\
compiler by \.{TANGLE} will have such underlines removed, and \.{TANGLE}
will check to make sure that two different identifiers do not become
identical when this happens. (In fact, \.{TANGLE} even checks that
the first seven characters of identifiers are unique, when lowercase
letters have been converted to uppercase; the number seven in this
constraint is more strict than \PASCAL's eight, and it can
be changed if desired.) The \.{WEAVE} processor will properly
alphabetize identifiers that have embedded underlines
when it makes the index.
\endcomment

Although a module begins with \TeX\ text and ends with \[code\] text, we have
noted that the dividing line isn't sharp, since \[code\] text can be included
in \TeX\ text if it is enclosed in `\pb'.  Conversely, \TeX\ text also
appears frequently within \[code\] text, because everything in ^:comments:
(i.e., between \[`\.{/*}' and `\.{*/}', or between~`\.{//}' and the next
newline\]) is treated as \TeX\ text. 
Furthermore, a module name consists of \TeX\ text; thus, a \.{WEB} file
typically involves constructions like `\.{if}(\.x\ \.{==}\ \.0)\
\.{@<Empty}\ \.{the}\ \.{|buffer|}\ \.{array@>}' where we go back and forth
between \[code\] and \TeX\ conventions in a natural way.
\endKnuth

In the original \WEB\ design, a module name (\.{@<\dots@>}) was not allowed
between the vertical bars, because the first occurrence of the name
signified the beginning of the code part.  Beginning with version~1.30,
this restriction has been removed.  Thus, one can include in his \TeX\
documentation statements like ``See section \.{|@<A@>|} for \dots''.  Since
code mode is allowed inside module names, it is now also possible to have
module names within module names, as in ``\.{@<A = |@<B@>|@>}''.
(Obviously, it's possible to abuse this flexibility.)

\subsection Fortran demo program. ^^(example!Fortran program(

To summarize and illustrate some of what has just been said, here is an
(incomplete) example of a \Fortran\ program that is intended to read some
data, process it, and graph the results. This uses several features that
have not yet been explained, namely macro definition, preprocessor
commands, and format commands, but these are either fairly obvious and/or
can be ignored for now.  This example tries to demonstrate how one should
liberally use named modules
^^{module!named}
to enhance the logical structure of each module
and to keep the length of each module quite short, and how to use vertical
bars
^^<bars, vertical> ^^<\>{"|..."|}>
to intersperse code mode with TeX'd documentation.
\HRULE
\verbatim{demo1.web}
\HRULE
\FWEAVE\ typesets this example as follows.
\HRULE
\typeset{demo1}
\HRULE
^^)rules!syntax)

^^)example!Fortran program)


\vfill\Eject

\subsection Modules versus functions.[4.11.3] 
^^[modules!use of] ^^[functions!use of]

Clearly the concept of \WEB\ modules leads to great flexibility  and
readability in the construction of source codes.  However, modules can also
be misused or, in particular, \It{overused}, ^^{modules!overuse of}
and these difficulties are not uncommon for beginning programmers in \WEB.  

\subsubsection When to use named modules.

\parinserto{5}{7}{0.7}
``Named modules should be used when the overhead of a function call is
unacceptable, such as, for example, in a computationally bound inner loop.''

The problem is that although in many ways modules are functionally quite
similar to functions or subroutines, they are not identical.  Of course,
modules do not take arguments, but that is not so much the point.  Of more
concern is that it is in principal possible to create a very large code
with just one main program (consider the above example), even though no
section is more than about a dozen lines long, just by nesting named
modules to arbitrary levels.  That this is undesirable is usually
emphasized when one attempts to debug such a code; he may find that it is
not easy to set a breakpoint at a module, whereas had each module been a
function call one could have set many breakpoints and obtained a detailed
picture of the control flow.  Also, many compilers have limitations on the
maximum length of a function.  A partial solution to this is discussed in a
later subsection on debugging, but it is nevertheless true that one should
often use function calls instead of modules.  Named modules should be used
when the overhead of a function call is unacceptable, such as, for example,
in a computationally bound inner loop.  They also find an important use in
making constructions such as large \&{switch} statements readable; each
case of the \&{switch} can be a separate module.  However, very large
blocks of code, especially in outer sections of the program, should
probably be accessed with function calls, if possible.  Note, though, that
certain blocks of code, such as \&{common} declarations in \Fortran, cannot
be replaced by function calls.  For such cases, the use of named modules is
almost always desirable.

As an example of this discussion, it would actually be better to code the main
program of the preceding example as follows:

{\codemode
program main
@<Common declarations@>
call input
call process
call graph
end
}
\noindent Since the main program is not inside a critical inner loop, the
slight extra overhead of the subroutine calls will be imperceptible, and
one can easily set a debugging breakpoint at each of the fundamental
subroutines \\{input}, \\{process}, and \\{graph}.  A named module is
properly used here to insert the common declarations, which cannot be
replaced by a subroutine call.

\dsubsubsection Self-documentation and cross-referencing for named modules and
identifiers. ^^{module!references}

One of the great virtues of employing named modules is that the names are
\It{self-documenting}.  For example, it is much more illuminating to see
``\WX98:Check that $\theta$~lies in the range $-\pi \le \theta < \pi$; issue
a warning message otherwise\X \X'' than to have to remember what the
statement ``\&{call} \\{check}'' does.  Furthermore, in the original
\WEB\ design it was not immediately obvious where \\{check} was defined.
One had to turn first to the index, look up \\{check}, then turn back to
the desired section.  The extra step of accessing the index is unnecessary
with module names, which have the relevant section number built in.

However, beginning with \FWEB\ version~1.20, certain identifiers such as
function names and macro definitions also carry the
section name in which they were defined, displayed as a subscript---e.g.,
\\{check}\WIN1{98}.  ^^{subscripts, module number} ^^{module!references}
Although this does not solve the problem of
self-documentation, it does expedite finding one's way around the code.
This mechanism is discussed further in the section on ``Forward
referencing'' below.

In fact, it's possible to the virtues of both self-documentation and
function calls if one is willing to do a bit of extra typing.  Consider the
following:

{\codemode
@<Check that $\\theta$ lies in the range $-\\pi \\le \\theta < \\pi$;
issue a warning message otherwise@>=
\Tab call check
}
\noindent With this trick, the documentation shows clearly what is really
happening, but one can still set a breakpoint at \\{check} for convenient
debugging. 

\subsubsection {\tt WEB} programming and \Unix.

In summary, both function calls and named modules can be used to good
advantage in \WEB\ programming.  If they are used properly, the resulting
product can be amazingly easy to understand and maintain.

\parinsert{2}{4}{0.35}
``{\ssbf WEB} and {\ssbf UNIX} are not in conflict.''

Nevertheless, the possibility of indiscriminate use of modules has led some
programmers, particularly those used to \Unix, to suggest that \WEB\
programming is a step backwards and defeats the utility of other tools such
as the \.{make} utility.  Those programmers will delegate each function to
a separate file, then use the \.{make} utility to keep them updated as
necessary.  However, although this keeps the amount of compiling to a
minimum, this extreme limit can also be criticized on the grounds that it
is very difficult to maintain a sensible, coherent documentation, which was
the primary goal of the \WEB\ system.  More reasonably, the ideal solution
lies somewhere between the two extremes.  Generally it is reasonable and
efficient to combine at least several functions into one source file.
Furthermore, all but the very shortest functions can benefit from being
broken into named modules, and common \WEB\ macros can be easily included
with each separate file.  \WEB\ and \Unix\ are not in conflict; they both
provide powerful tools that can be simultaneously applied to complicated
programming problems.  Both systems provide the programmer with a great
deal of power.  It is up to him to use that power wisely and with
discipline.  As Knuth admits, the users of \WEB\ must be sophisticated, but
they reap significant rewards in return.

\section The PHASES of \WEB.[5.3]  ^^(\>{WEB}!phases of(

It is not necessary to know in great detail just how \WEB\ accomplishes its
various tasks in order to use it effectively. However, to fully understand
some of the material to follow, especially topics related to macro
processing, it is necessary to appreciate that \WEB\ processes its input in
several distinct ^[phases]: two for \TANGLE; three for \WEAVE. These phases
are explained briefly here.

First, we must remark that the \WEB\ processors are best viewed as
consisting of three parts: an \It{input driver};
^^{driver!input}
the \It{processor proper}; and
an \It{output driver}.
^^{driver!output}
Each source language has (at least in principle) a distinct input driver.
The role of the input drivers is to preprocess the incoming text into a
uniform syntax that can be understood by the processor proper. For example,
idiosyncratic commenting styles such as \Fortran--77's column~1 convention are
converted by the input driver to the standard C~style that the innards of
the processors understand. For \WEAVE, the output driver is common to all
languages; it creates the \.{tex}~file. For \TANGLE,
the output driver is more or less the inverse of
the input driver; it creates~\.c, \.{for}, \.{rat}, or~\.{tx}~files.
In the following discussion, ``input'' is best thought of
as the input to the processor proper, or equivalently as the preprocessed
output of the input driver.

\subsection Phase 1.

For both processors, phase one involves \It{^{tokenization}} of the input.
If the input is \TeX\ material, it is skipped by \TANGLE\ or absorbed
essentially unchanged by \WEAVE. Code material is broken up into
identifiers, numerical constants, character strings, etc., and these are
represented by special codes. For ease in working with \WEB\ macros,
the concept of \It{identifier} is generalized
somewhat from the syntax of any of the supported source languages:
^:identifiers: are character sequences of arbitrary length that contain either
an alphabetic character (\.{A-Z} or \.{a-z}), a digit (\.{0-9}), an
underscore~('\.\_'), a dollar sign~('\.\$'), or, when the language is
neither~\C, \Cpp, nor \Fortran--90, a per~cent sign~('\.\%');
they may not begin with a digit. 
Case is always significant. ^^[case, significance of]
Thus, examples of unique identifiers are

{\codemode
a, A, UPPER_and_lower_case, i5, SYS$TEST, $1, _reserved, %loc
}
\noindent Avoid defining macros or C~identifiers that begin with an
underscore; such 
identifiers may be used internally by the system.   Dollar signs or (generally)
per~cent signs are permitted since some compilers use them to identify
extensions to the standard languages.  It is common to enter the source
code entirely in lower case, thereby reserving upper case for possible use
in macro definitions.  In particular, the reserved words of~C or \Fortran,
such as \&{for} or \&{dimension}, are understood only in lower case.

\parinsert{2}{5}{0.5}
``Avoid defining macros or C identifiers that begin with an underscore.''

When an identifier or module name is recognized, both \TANGLE\ and \WEAVE\
store it in a table, along with its special code. Otherwise, however, the
two processors do different things in phase one. ^^[phase!1]
\TANGLE\ ^^[phase!1!\>{TANGLE}]
stores all of the
tokenized code, filing it into the appropriate (unnamed or named) module.
It also memorizes macro definitions.
\WEAVE, on the other hand, does \It{not} store the code during phase one.
^^[phase!1!\>{WEAVE}]
Rather, it merely processes any format (\.{@f}) definitions or operator
overload 
(\.{@v}) commands (both explained later) and constructs a 
cross-reference table for the identifiers and module names. This
preliminary pass is required in order that forward references to named
modules and certain identifiers can be resolved.
^^{modules!forward references to}

\subsection Phase 2.

During phase two, ^^[phase!2] ^^[phase!2!\>{TANGLE}]
\TANGLE\ outputs the code it has stored. As explained
earlier, it begins with the contents of the unnamed module.
^^{module!unnamed}
If at any point it encounters a reference to a named module, 
^^{module!named}
it takes a detour to dump out the contents of that module. Since modules may
contain references to other modules, and such references can be nested to
arbitrary depth, the output routine is recursive.  As text is output,
each identifier is examined to see whether it has been defined as a \WEB\
macro. If so, the macro is expanded;
^^{macro!expansion}
that expansion procedure is also
recursive. In the \Ratfor\ mode, certain identifiers such as \&{for} or
\&{switch} have special significance. These are not macros, exactly;
rather, they are special keywords signifying that special actions should be
taken on the text that follows. When one of these keywords is recognized, a
special \It{statement translation function} is invoked.
^^{statement!translation}
The input to that
function is the raw output of \TANGLE. The function may request further output,
possibly storing up text and outputting it in a different order, possibly
inserting additional statements such as \&{goto} into the output. The
ultimate output from the statement translator will be the
\Fortran\ equivalent of the original \Ratfor\ construction. Macros and
module names will have been expanded properly during that output.

Thus, at the end of phase two of \TANGLE\ all of the code will have been
output in the appropriate order, in a form acceptable to a language
compiler.  (See the example in Appendix~D.)

Phase two of \WEAVE\ ^^[phase!2!\>{WEAVE}]
is more complicated. For each module, 
\WEAVE\ reads the 
source file again. It copies the \TeX\ material to the output essentially
unchanged. It tokenizes the code and stores it along with the
cross-reference information that it collected during phase one.  At the end
of the module, it then analyzes the code hunting for constructions it
understands, such as expressions, loops, entire functions, etc. These are
processed and output into a series of \TeX\ macros that will typeset the
code in a useful, visually appealing way.  (See the examples in Appendices~B
and~E.) 

\subsection Phase 3.

\TANGLE\ has no phase~three.

Phase three ^^[phase!3] ^^[phase!3!\>{WEAVE}]
of \WEAVE\ sorts the cross-reference information, 
^^{cross-references}
and writes out the ^{index}, alphabetized list of module names,
^^{module names!alphabetized list of}
and the ^{table of contents}.  In order to expedite advanced editing and
other tasks, both the index and list of module names are written to
separate files, which by default are named \.{INDEX.tex} and \.{MODULES.tex}.
^^{\>{INDEX.tex}} ^^{\>{MODULES.tex}}
(These can be changed with the style file; see below.)
^^)\>{WEB}!phases of)

\dsection LANGUAGES.[6.1]  ^^(languages(

This version of \FWEB\ supports a variety of source languages: 
\Fortran\ (both \Fortran--77 and \Fortran--90), ^^{language!Fortran:\FORTRAN}
\Ratfor\ ^^{language!Ratfor}
(both \Ratfor--77 and \Ratfor--90; to be explained shortly), \C, \Cpp,
^^{language!C} ^^{language!\Cpp} 
and \TeX. ^^{language!\>{TEX}}  
(A future version may support the language 
\.{MAKE}, defined to be the syntax of \Unix\ make files.)
These languages can be intermixed within one
\WEB\ run.  In the simplest situation the programmer will use just
one language.  However, it is not uncommon to code the outer, control part
of a large program in, say, the C~language while writing the inner,
computationally bound routines in \Fortran.  In such situations, \FWEB's
language facilities are quite useful, since it enables one to maintain the
documentation for the entire code in one unified source file.

\comment
Internally, \FWEB's notion of
language sometimes differs somewhat from the traditional one.  In
particular, most 
people would likely say that~\C\ and \Cpp~are distinct languages, in the
sense that one uses different compilers to process them.  However,  for
\It{almost} all purposes \C~is a proper subset of~\Cpp.  For this reason,
in order 
to keep the size of various internal tables as small as possible and in
order to conveniently share large and complicated blocks of code, \WEB\
treats~\C\ and~\Cpp\ as two dialects of one language, namely~\.C.  A
subsidiary flag is used to distinguish between the two when necessary.
Thus, as explained below, one uses the commands~\atcmd{c} or~\atcmd{c++} to
process standard~\C\ or~\Cpp, respectively.  Both of these commands sets
\FWEB's current language to~\.C; the ``\.{++}'' sets a subsidiary flag.  The
same mechanism is used to distinguish between \Fortran--77~(\atcmd{n}) and
\Fortran--90~(\atcmd{n9}), 
which truly are dialects of the single language \.{FORTRAN}, and between
\Ratfor--77~(\atcmd{r}) and \Ratfor--90~(\atcmd{r9}).
\endcomment

\subsection Selecting a language.[6.1.3]

It is very simple to tell \WEB\ which language is in effect at any point.

\subsubsection Language abbreviations. ^^:language!abbreviations:

Each language has an abbreviation that can be used to identify it.  These
are as follows: 
$$\vbox{\halign{#\hfil&\ ---\ '{\tt#}'\hfil\cr
\C*&c\cr
\Cpp*&c++\cr
\Fortran--77*&n\cr
\Fortran--90*&n9\cr}}
\qquad
\vbox{\halign{#\hfil&\ ---\ '{\tt#}'\hfil\cr
\MAKE&k\cr
\Ratfor--77*&r\cr
\Ratfor--90*&r9\cr
\TEX&x\cr}}
$$
(Strictly speaking, only the first character is the abbreviation; any
subsequent text is an optional argument, as discussed in more detail below.
Also, note the `\.n' for fortra\.N; an `\.f' conflicts with the format
command~\atcmd{f}.)  
Each of the starred languages can be invoked by its own command-line option
or control code (these are explained below in more detail).  For example,
\C~can be invoked from the command line by the option~`\.{-c}', and from
within the \.{web}~source by~\atcmd{c}.  Other languages, such as \.{TEX} or
(in the future)
\MAKE, must be invoked by the general language command~`\.{-L$l$}' or
\atcmd{L$l$}, ^^{\={-l}{-L{\it l}}}
where $l$~is one of the language symbols listed above.  (Case is
significant; `\.{-l}'~means something entirely different.) ^^{\>{-l}}
For example, one
can invoke the \.{\TeX} language by~\atcmd{Lx}.  This general command also
works for the starred languages, so that \atcmd{n}~is equivalent to~\atcmd{Ln}.

\subsubsection Global language.

\FWEB\ has the concept of a \It{global language}.
^^:language!global:
The global language is defined to be the language in force when the first
module is encountered; namely, at the very end of the limbo stage.
^^[limbo!section!changing language in]
It is used as the starting language of the unnamed module and of the \TeX\
parts of each section.  The default global language is
\Fortran--77, ^^:language!global!default: ^^{language!Fortran:\FORTRAN}
a reluctant concession to the physics world. However,
\It{it is 
not recommended that you use \Fortran--77 for new code}, as you will lose a
good deal of the statement-processing abilities of \FTANGLE. First, you
should consider switching to~\C\ or~\Cpp, which are choices superior to
\Fortran\ for many applications. However, if you choose to write in a
\Fortran\ dialect, then \It{it is 
strongly recommended that you use \Ratfor}, ^^{language!Ratfor}
as described elsewhere in
this document. Your code will be easier to write (it will be logically
clearer and will involve fewer keystrokes), the result will be
substantially more readable, and, therefore, you will ultimately be more
productive.

\parinsert{2}{5}{0.4}
``It is not recommended that you use Fortran--77 for new code.''

One can override the default global language of \Fortran--77 in two ways. 
^^{language!global!setting the}
First, although it
is {\it not recommended} except for special situations, one can set it from the
command line by using one of the options `\.{-c}', `\.{-r}', `\.{-n}',
or~`\.{-L$l$}'. 
^^{\>{-c}} ^^{\>{-r}} ^^{\>{-n}} ^^{\={-l}{-L{\it l}}}
Second, you can insert one of the language switching commands
\atcmd{c}, \atcmd{r}, \atcmd{n}, or~\atcmd{L$l$}
^^{\>{@c}} ^^{\>{@r}} ^^{\>{@n}} ^^{\={@l}{@L{\it l}}}
anywhere in the limbo section. Note that if
you have such an explicit language command in your file, it will override
anything that was said on the command line. (You will be warned.)  The best
practice is to put the global language command at the very beginning or the
very end of the limbo section.  (If you put it at the beginning, it must
at present follow any \.{@z\dots@x} ignorable commentary.)
^^{commentary!invisible} 
If you're programming only in \Fortran--77, you don't need the 
\.{@n}~command. However, as a matter of style, and for compatibility with
future releases, it's best to always insert a language command explicitly.

\subsubsection Changing languages within modules.
^^[language!changing!within modules] ^^[module!language of]

All modules, both named and unnamed, have a language. The \TeX\ part of
each section will begin in the global language. Now although language
doesn't matter for \TeX\ text, it does matter if you shift into code mode
^^{code!mode} ^^{mode!code}
by using vertical bars.  Unless told otherwise, code between vertical bars
will be in whatever language is currently in force (generally, this will be
the global language). If, however, you want that code to be interpreted
according to some other language, you can put a language command
immediately after the opening vertical bar, as in `\.{|@n real a(0:n)|}' or
`\.{|@r repeat \{i=f(i);\} until(i > 10);|}'; that language switch will be
local to the barred material. 

Except for this local use of language commands, it is safest (because of
certain restrictions in the \Fortran\ mode) and logically and visibly
clearest that language commands begin in column~1, on a line by themself.

You can also place a language command anywhere in the \TeX\ part, not
just between bars, to reset the language for the rest of that part, but
this is neither recommended nor usually necessary.

\parinsert{2}{5}{0.55}
``You can change languages in the unnamed module, but that change is local
to one section.''

When the command~\atcmd{a}, which signifies the start of the unnamed module,
is encountered (either for the first or for subsequent times), the language
reverts to the global language. You can change languages in the unnamed
module, but that change is local to one section; it is cancelled by the
next~\atcmd{*} or~\atcmd{\ }. \FTANGLE\ sorts out the languages and deflects
the code to the appropriate output files. \FWEAVE\ prints the language
commands as a marginal note, and it identifies the language of any module
name not in the global language with a superscript, as in
\atcmd{<C code@>}$^{\textstyle\tt C}$.

\parinsert{1}{5}{0.6}
``The code parts of named modules inherit the language in force when
that name was first encountered.''

The code parts of named modules inherit the language in force \It{when
that name was first encountered}. That language attribute propagates
through all levels of nesting, so that if you have a named module in, say,
the C~language, all named modules referenced for the first time in that
module will automatically be interpreted in~C; you don't need to preface
each of those (possibly many) modules with an explicit~\atcmd{c}.

However, if, for example, the global language is \Fortran, there must be at
least one~\atcmd{c} somewhere in your file in order to mix in any C~routines
at all. The most painless way to do this is to switch languages in the
unnamed module. Put a language command just before a reference to a named
module that you want to be interpreted in~\C. That one command is all you
need to have everything connected with that named module also be understood
to be in~C.

\It{When the language is \Fortran--77, begin all \atcmd{}~commands in
column~1.} This restriction is imposed in order to help simplify the job of
the \Fortran\ input driver, which converts the column-oriented syntax of
traditional \Fortran\ to the free-form syntax that the innards of the \WEB\
processors understand.  It's not a bad programming style in any event.

\subsection Demo program with two languages. 
^^(example!program with two languages( 

As an example, here's how you might handle a main program in \Fortran\ and
some subroutines written in~\C, all of which are here put into the unnamed
module. 
^^<language!changing>
\HRULE
\verbatim{demo2.web}
\HRULE
\FWEAVE\ typesets this example as follows.  Note the marginal
notation~\.{@Lc}, which marks the language change~\atcmd{c}.  Also notice how
module names not in the global language are superscripted with a language
symbol.  
\HRULE
\typeset{demo2}
\HRULE
\noindent When the definition of module \.{@<C code@>} is encountered,
\FWEAVE\ will properly format it in~\C. \FTANGLE\ will also do the
right thing, spitting the main program out into a \.{FOR} file but the
\.{@<C code@>} into a \.{C} file. Furthermore, the modules
\.{@<Compute@>} and \.{@<Graph@>} will also be properly interpreted in~C, the
language that they inherit from \.{@<C code@>}.

^^)example!program with two languages)

\vfill\Eject

\subsection Language commands in the definition part. 
^^:language!of definition part:

\parinserto{2}{4}{0.4}
``Identifiers also have language attributes.''

Language commands may also be inserted in the definition section, and are
sometimes necessary.  This situation arises because
identifiers also have language attributes;
^^{identifiers!language attributes for} ^^{language!and identifiers}
this includes the special cases of reserved words and intrinsic functions,
and it implies that formats and outer macros (see below) are interpreted
according to one particular language. Although possibly a bit complicated,
this allows one to handle the important case where an identifier is 
a reserved word in one language but not in another.  For example,
\&{dimension} is a reserved word in \Fortran\ and \Ratfor, but not in~\C.
The only time when you have to worry about this explicitly is when you're
formatting a new identifier with~\atcmd{f}. (Formatting is explained below.)
You must be in the language in which you intend that identifier to be used.
This means you may have to switch languages in the definition section, even
if the identifier you're formatting is used in a named code section
immediately below whose language is already known. This is necessary because
modules start off in the global language and the language of the named
module isn't known until the module name is encountered,
\It{after} the definition section. Had one been thinking about multiple
languages when the \WEB\ system was first designed, he might have devised a
somewhat more elegant scheme, but it's too late now. In practice, the
present scheme does not seem to lead to too many annoyances.

Two built-in \WEB\ functions, \.{\_LANGUAGE} and \.{\_LANGUAGE\_NUM}, 
^^{\>{\UL LANGUAGE}} ^^{\>{\UL LANGUAGE\UL NUM}}
are sometimes useful in writing conditional macros.  See the discussion
about built-in functions below for their definition.
The \WEB\ built-in function \.{\_LANGUAGE}  
(built-in functions are explained below)
expands to either `\.{\_C}', `\.{\_CPP}', `\.{\_N}',
`\.{\_N90}', `\.{\_R}', `\.{\_R90}', or~`\.{\_X}', depending on the
language currently in effect. 
^^{\>{\UL C}} ^^{\>{\UL CPP}}
^^{\>{\UL N}} ^^{\>{\UL N90}}
^^{\>{\UL R}} ^^{\>{\UL R90}}
^^{\>{\UL X}}

\dsubsection Optional arguments to language commands. ^^:arguments!optional:

\parinserto{2}{5}{0.6}
``Language control codes may always be optionally followed by text enclosed
by square brackets.''

Some of the language commands may have optional arguments.  For example,
\Fortran--90 is treated as a dialect of the fundamental language~\Fortran.
It can be invoked by the commands~`\.{-n9}' or~\atcmd{n9}.  Here the
text~``\.{9}''~is the optional argument.  An other example of such a command
is~\atcmd{r9}, which sets the
language to \Ratfor--90.  The latter means that \Ratfor\ syntax is
understood along with \Fortran--90 keywords, \It{and} that the \Ratfor\ is
translated into \Fortran--90 rather than \Fortran--77.  All the possible
arguments relating to languages are detailed in the section below on
command-line options, and in Appendix~L.

The preceding examples are special cases of a more general mechanism.
Language control codes may always be optionally followed by text enclosed
by square brackets.  ^^[brackets, square] ^^[arguments!to language control
codes] 
One may put inside the square brackets (almost)
any option that may be put on the command line, allowing parameters to be
reset at each language change.  As a useful shorthand, if a language
control code is followed 
immediate by text (non-white space) that is not begun by a left bracket,
the text is automatically prefaced by a hyphen and the control code, then
enclosed by brackets. That is,
$$
	\hbox{\.{@n}\It{text}} \equiv \hbox{\.{@n[-n\It{text}]}}
$$
so we see, for example, that
$$
	\hbox{\.{@n/}} \equiv \hbox{\.{@n[-n/]}}
$$
(It may be interesting to know that \Cpp~is handled in this same
way---i.e., ``$\hbox{\.{@c++}} \equiv \hbox{\.{@c[-c++]}}$'', although one
will generally not need to be concerned with this.)
Parameters in force for a given language are saved when leaving that
language and restored when returning to it.  Thus, one can mix modules
with different dialects of \Fortran, as in

{\codemode
@n9
@
@A
\Tab @<Fortran--90 stuff@>
\Tab .
\Tab .
@n7
\Tab @<Fortran--77 stuff@>
\Par
@ The code part of this section will be in the global language 
of Fortran--90.
@<Fortran--90...@>=
\Tab .
\Tab .

@ This section will be in Fortran--77.
@<Fortran--77...@>=
\Tab .
\Tab .
}

Although it would sometimes be convenient, one cannot at present use
shorthand such as~\atcmd{n9\&}; you must say \atcmd{n9[-n\&]}.  This
restriction is necessary because some arguments expect additional
characters to follow.  Thus, the form \atcmd{n9\&} is, according to the rules
above,  equivalent to \atcmd{n[-n9\&]}, so the ampersand would be
interpreted as an (invalid) subargument to ``\.{-n9}''.

Certain options such as macro definitions are forbidden as optional
parameters following a language code.  These are specified in Appendix~L.

The bottom line about languages is that if one uses only one, one needs to do
nothing more than place one language command somewhere in the limbo section.
If one mixes languages, one needs to place at least one additional language
command somewhere in the unnamed module; one has to be slightly more
alert, but not very much so. The intent is that languages should work the way
one expects them to, without having to do much of anything.
^^)languages)

\dsection MACROS.[7.7] ^^(macros(

\parinserto{2}{4}{0.5}
``Say `{\ssbf YES}' instead of `1', or `{\ssbf EPS}' instead of `1.0e-6'.''

Macro processing---definition of shorthand, readable symbols for otherwise
obscure, tedious, or repetitive constructions---is one of the most
effective ways to enhance one's coding productivity 
^^[productivity!enhancing]
and the ultimate
readability of a code. For example, virtually no numerical constants should
appear explicitly in a well-written source code; they should be defined
symbolically in terms of macros instead. Say `\.{YES}' instead of~`\.1', or
`\.{EPS}' instead of \hbox{`\.{1.0e-6}'}. If later you decide that
$\epsilon$~should be~$10^{-7}$ instead of~$10^{-6}$, you need to change
just the single macro definition line rather than to edit many lines of the
source code; furthermore, a well-chosen symbolic name carries much more
meaning than a raw number. The C~language has a built-in preprocessor, and
that is one of the major virtues of~C.  Unfortunately, \Fortran\ lacks a
macro preprocessor. It does contain the
\&{parameter} statement. However, that statement is highly restrictive: its
scope is restricted to each individual subroutine, and arguments are not
allowed. Since often more flexible macro processing is useful, many people
adopt the strategy of running their 
\Fortran\ code through a preprocessor such as \Unix'~\.{m4}. ^^{\>{m4}}
This extra
processing step is annoying at the very least, and also requires one to
learn the syntax of the preprocessor. Although these steps cannot be
entirely avoided, their difficulty can be minimized. Thus, \FWEB\
has its own built-in macro preprocessor. This is patterned after
the ANSI C~preprocessor, ^^{preprocessor!ANSI C}
so that users who are either already familiar with~C or who are using
\FWEB\ to program in both~C and \Fortran\ are presented with a
syntax that is essentially language-independent. In practice, this turns
out to be an important consideration. The design and operation of the
C~preprocessor are also arguably more convenient than \.{m4} for many
applications, although this is certainly a matter of taste to some extent.

\dsubsection WEB macros.[7.1.12]

\parinserto{2}{4}{0.35}
{\ssbf WEB} macros are defined by `{\ssbf @m}'.

\WEB\ macros, sometimes called ``internal'' or ``inner'' macros,
^^:macro!internal: ^^:macro!inner:
are defined by the command~\atcmd{m}. ^^{\>{@m}}
Temporarily, let us assume that these
definitions are made in the definition section (as they should always be,
except for special considerations described below).  In general, \WEB\
macros are expanded when the code is being \It{output} in phase two. \[The
exception to this is when a macro is encountered in a \WEB\ preprocessor
statement (beginning with~\atcmd{\#}; see below); then, it is expanded
immediately.\] As defined for ANSI~C, there are two macro forms:
``object-like,'' and ``function-like.'' 

\subsubsection Object-like macros. ^^:macro!syntax!object-like:
^^[syntax rules!\WEB\ macros]

Object-like macros have no arguments; they have the form
^^:macro!object-like:

{\codemode
@m \Identifier\ \Replacementtext\ \Optcmnt
}
\noindent Here and elsewhere, \Replacementtext\ is an arbitrary string of
symbols (except that module names are not allowed). The \Replacementtext\
may be continued on subsequent lines.
^^[macro!continuing]
Unlike the C~preprocessor, which
requires continued lines to end with a backslash, no backslashes are needed
(or allowed) for macros continued in the definition section. The reason for
this is that the end of the definition 
can be determined from the context; it occurs when the next definition
(\atcmd{m} or~\atcmd{d}), format command (\atcmd{f}), preprocessor
command~(\atcmd{\#}), limbo text command~(\atcmd{l}), operator overloading
command~(\atcmd{v}), identifier overloading command~(\atcmd{W}), unnamed
module command~(\atcmd{a}), module name~(\atcmd{<}), or new module command
(\atcmd{*} or~\atcmd{\ }) is encountered. The definition of \Identifier\ is
memorized during  phase one. Then, whenever the \Identifier\ is encountered
as the code text 
is being output in phase two, it is replaced by the \Replacementtext\
(which is then rescanned for further macro substitutions).

Simple examples of object-like macros are
^^<macro!object-like>

{\codemode
@m NO 0 // An object-like macro (having no arguments).
@m YES 1 // It is conventional to use 1 for true, 0 for false.
@m PI 3.14159 // Most constants should be given readable symbolic names.
@m ARG_LIST x,kx,ky,kz
@m DCL_ARGS real x;
\Tab\Tab integer kx,ky,kz // Notice how easily this macro was continued.
@m BLANK // A null macro, with no replacement text.
}

Object-like macros are closely related, though not identical, to \Fortran's
\&{parameter} statement. ^^[statement!\<{parameter}]
	^^{declarations!\<{parameter}} 
The differences are that a \WEB\ macro is known throughout the entire code
and will appear in expanded form in the tangled output, whereas a
\&{parameter} declaration is local to a subroutine and is expanded by the
\Fortran\ compiler, rather than by \TANGLE. This means that your tangled
output may be more readable if you use \&{parameter} statements instead of
\WEB\ macros. However, although this may be adequate in simple cases, it
will often not be a viable option. For example, to effectively use the
preprocessor facility to be described shortly one must use \WEB\ macros.
Furthermore, one can supply arguments to \WEB\ macros, a very useful
feature that we describe now.

\subsubsection Function-like macros. ^^:macro!syntax!function-like:

The syntax of function-like macros is
^^:macro!function-like:

{\codemode
@m \Identifier(\Arglist) \Replacementtext\ \Optcmnt
}
\noindent The \Arglist\ is a comma-separated list of parameter names. (The
list may be empty.) If the \Arglist\ is terminated by an ellipsis
(\.{\dots}) instead of a parameter name, the macro is allowed to have a
variable number of arguments (unlike ANSI~C, which permits only macros with
a fixed number of arguments). 
In simple cases things work the way one would expect:
the actual arguments are determined and the parameters in the
\Replacementtext\ are replaced by those arguments. The general mechanism is
slightly complex and is explained below. First, however, here are simple
examples of function-like macros.  (In some of the examples to follow, the
result of the macro expansion is shown in a comment, enclosed by single
left and right quotes. These quotes are not to be confused with
\Fortran's character strings; they would not be part of the actual macro
expansion.)
^^<macro!function-like>

{\codemode
@r
@* FUNCTION-LIKE MACROS.
@m MULT(a,b) ((a)*(b)) // A macro with 2 args. $a$ and~$b$ are dummies.
@m EAT(x) // Gobble up the argument.
\Par
@f LOOP for
@m LOOP() do i=0,N;
\Tab do j=0,N
\Par
@A
z = MULT(x-5,y); // Expands to `z = ((x-5)*(y));'.
if(z < 0.0) return NO; // Uses the object-like macro~|NO| defined above.
LOOP()
\Tab \{\dots\}
}

Several remarks can be made about the previous examples. First, a standard
remark:  the
parentheses in the replacement text of~\\{MULT} are absolutely essential;
consider what would have happened if \\a had not been parenthesized.
Second, one may ask why \\{LOOP} was defined as a function-like macro with
no arguments instead of as an object-like macro. \FTANGLE\ would create the
same expanded code in either case. However, it is useful to define things
as we did in order to help \FWEAVE\ format the macro properly. The format
command tells \FWEAVE\ to treat \\{LOOP} in the same way that it treats
\&{for}. In \Ratfor\ the keyword \&{for} expects a parenthesized expression
to follow; our definition of \\{LOOP} accomodates that. Thus, in the output
it will actually appear in boldface, and the body of the \&{LOOP} will be
properly indented.

\dsubsubsection Extensions to \WEB\ macro syntax.
^^:macro!syntax!extensions to: ^^:extensions!to \WEB\ macro syntax:

There are two special (and partly experimental) variants of the
\atcmd{m}~command.  The construction~`\atcmd{m*\ \dots}' means that the
macros is allowed to be recursive. 
^^{macro!recursive} 
\It{(However, recursive macros
are not implemented in the present version.)}  The construction
`\atcmd{m[\It{letters}]\ \dots}' says that this macro is associated with
^{automatic insertion} material.  See the subsequent discussion of \Ratfor\
for more details.

\dsubsubsection Stringizing.

\parinserto{2}{5}{0.6}
``Several special tokens beginning with `{\ssbf\#}' may appear in the
replacement text of \WEB\ macros.''

Several special tokens beginning with `\Stringize' may appear in the
replacement text of \WEB\ macros.  The most important of these are
`\Stringize' and `\Paste', which are borrowed from the ANSI C~preprocessor.
In the ANSI usage, the token `\Stringize' (``stringize'') ^^[stringizing]
must appear before a macro parameter (dummy argument). It and the parameter
will be replaced by a string literal (appropriate for the language in force
at the moment of expansion) constructed out of the corresponding actual
(unexpanded) argument. (In \Fortran, strings are delimited by single
quotes; in \Ratfor\ and~C, they are delimited by double quotes.)  For the
simplest possible example,

{\codemode
@r
@* STRINGIZING.
@m S(s) #s
@A
S(Hello); // Expands to `"Hello";'.
@n
\Tab S(Hello) // In Fortran, the same macro expands to 'Hello'.
}

What happens when the argument to a stringize operation is already a
string? The answer, consistent with ANSI~C, is that the original quotes are
escaped appropriately and the whole thing is surrounded by quotes.
Therefore, \.{"hello"} stringizes to \.{"\\"hello\\""} in~C. This may not be
what you want; see the discussion of the \.{\#*}~operator below.

\dsubsubsection Making single- and double-quoted strings.

^^:\>{\PM'}: ^^:\>{\PM""}:
If one stringizes a parameter in~C, the parameter will always be enclosed
in double quotes.  In cases involving manipulations of single characters,
one may instead desire single quotes.  To stringize a parameter and force
it to be enclosed in a particular kind of quote, use the \.{\#'} or
\.{\#"}~commands, which are extensions to~ANSI.  Thus, if in~C one defines
`\atcmd{m A(c) \#'c}', then ``\.{A(x)}''~expands to~``\.{'x'}''.  

\dsubsubsection Token pasting.

The token `\Paste' (``paste'')
^^[pasting] ^^:\>{\PM\PM}:
merges together the things on
either side of it.  If possible, a new identifier is created.  For example,
$\hbox{\.{pas\paste te}}$~becomes the new identifier
$\hbox{\.{paste}}$; however, nothing effectively happens if one says
`$\hbox{\.{pas\#\#(}}$'. Note that the token-pasting operation can create new 
identifiers that may themselves be macros; these will be expanded when the
result is rescanned. For a  simple example,
^^<pasting>

{\codemode
@* PASTING.
@m PASTE(a,b) a##b
@m paste 1
@A
PASTE(pas,te) // Expands to `1'.
}

\dsubsubsection Macro expansion.

Macro expansion is intrinsically recursive, and one must be aware of the
order of expansion of various objects.  The complete expansion of a macro
proceeds through several steps.  The intent is that the procedure emulate
that of the ANSI~C preprocessor.

^^[macro!expansion]
\parinsert{2}{4}{0.4}
``Macro expansion is intrinsically recursive.''

First, the identifier is recognized and the expected number~$n$ of
arguments is determined.
^^[macro!arguments]
If the identifier is object-like, a
parenthesized, comma-delimited list of actual arguments is expected (except
that if $n = 0$, there should be no arguments inside the parentheses). It
is an error if the parentheses aren't found or if the actual number of
arguments does not agree with the original definition. Within the
parentheses, commas protected by balanced parentheses do not count in
determining the end of the argument. Thus, the second argument to
the three-argument macro call `\.{MACRO(a,(b,c),d)}' is `\.{(b,c)}'.

Next, the replacement text associated with the macro is examined. If that
text contains instances of parameters preceded by `\Stringize', 
^^{stringizing}
both `\Stringize' and the parameter are replaced by a string built out of the
actual argument (which is not expanded). If there are parameters preceded
or followed by `\Paste',
^^{pasting}
those parameters are replaced by their corresponding actual arguments;
again, these arguments are \It{not expanded}.  Otherwise, parameters are
replaced by the actual arguments \It{after those arguments have been
exhaustively scanned for further macro expansions}.

After argument substitution, any paste operations are performed. Then
the result is rescanned for any further macros, which will be, in general,
expanded. Rescanning continues until nothing was expanded on the last pass.
For example, given the definitions
^^<pasting> ^^<stringizing>

{\codemode
@c
@m A 1
@m B 2
@m AB 3
@m C(a,b) a + a##b + #b
}
\noindent the macro call \.{C(A,B)} becomes after argument substitution and
pasting `\.{1 + AB + "B"}'; this is rescanned to yield the final result
`\.{1 + 3 + "B"}'. Note that macros inside strings are not expanded, and
that macro rescanning does not simplify numeric expressions such as $1+3$.
(Such simplifications can be accomplished by the \.{\_EVAL} built-in function
described below.)

In one important situation macros are not expanded. If a macro is being
expanded and its name is encountered again during that expansion, then it
is not expanded. This prevents various kinds of infinite recursion, 
^^[macro!recursion]
the simplest candidate being \atcmd{m A A}---this expands to `\.{A}', not an
infinite loop. Also, consider the previous example of \.{PASTE(a,b)} and
experiment to find out what happens when you say `\.{PASTE(PAS,TE)}'. (This
construction is illegal.)
^^<stringizing> ^^<pasting>


{\codemode
@c
@ Here are further examples of stringizing and token-pasting:
\Par
@m P(s) #s = s // Displays the result of a macro expansion.
@m VAR(i) var##i // Makes a new identifier name.
@m RECURSE(a,b) a##b(a,b) // Possibility for recursion here.
@m X 1
@m Y 2
@m Z ZZ
@m XY Z
@A
P(VAR(2)) // -> `"VAR(2)"=var2'
P(RECURSE(X,Y)) // -> `"RECURSE(X,Y)"=ZZ(1,2)'
P(RECURSE(RE,CURSE)) // -> `"RECURSE(RE,CURSE)"=RECURSE(RE,CURSE)'
}
\noindent Note that the last example did not get hung in an infinite loop.

^^(macro!extensions( ^^[extensions!to ANSI C macro syntax]
The macro facilities that have been described so far are intended to
emulate those of ANSI~C. A wide variety of tasks can be accomplished with
them.  Although in the following paragraphs we describe various \FWEB\
extensions to the ANSI~C preprocessor, \It{it is recommended that you
employ these only as a last resort}. The sparser the constructions and
features that you deal with, the less likelihood there will be for
programming errors.

\vfill\Eject

\subsubsection Including a comma in a macro argument.

\parinserto{1}{3}{0.6}
To include a comma in a macro argument, use the `{\ssbf \#,}' token. 

Since the arguments of macros are delimited by commas, it is not
immediately apparent how to
introduce a comma as part of a macro argument.  To do so, use the
`\.{\#,}'~token.  
^^:\>{\PM,}:
^^{commas!as delimiters of macro arguments}
^^{commas!as part of a macro argument}
For example,

{\codemode
@m A(x,y) [x][y]
@m B(x) A(x)
@a
B(3#,2) // -> `[3][2]'
}
\noindent Had one tried here to say ``\.{B(3,2)}'', he would have elicited
an error message, since \.{B}~is defined with only one argument.  

\subsubsection Concatenating strings.

\parinserto{1}{4}{0.55}
The {\ssbf FWEB} macro preprocessor concatenates adjacent strings.

In ANSI~C, adjacent strings, possibly separated by white space, are
concatenated on input.  Thus,  ``\.{"a"\ "bc"}'' is equivalent
to~``\.{"abc"}''.  \FWEB\ does not do such concatenation when reading \WEB\
source code; however, the \FWEB\ macro preprocessor does do so.  Thus, the
expansion of the macro definition `\atcmd{m\ A\ "1""23"}' will
be~``\.{123}''.  This facility is useful because the preprocessor does not
expand macros inside quoted strings.  Thus, with

{\codemode
@c
@
@m PW sexylady
@m MSG "The password is '"_STRING(PW)"'."
}
\noindent \\{MSG}~expands into ``\.{"The password is 'sexylady'."}''.  This
feature should be particularly useful in \Fortran\ or \Ratfor\ for easily
constructing readable error messages.

\dsubsubsection Quoting macros.

In some situations, it is desirable to prevent a macro from being expanded.
Enclosing a macro with special characters to prevent expansion is sometimes
called ``quoting'' the macro.
^^:macro!quoting: ^^{macro!preventing expansion of}
In other preprocessors such as \.{m4}, often
left and right square brackets are used to prevent expansion; each time a
pair of brackets is encountered, the outer brackets are stripped off. For
example, with the definition \atcmd{m N 10} the \Fortran\ source statement
`\.{[N] = N}' would expand to `\.{N = 10}'.  The \.{m4} preprocessor
provides the \&{changequote} command ^^{\<{changequote}}
to set the quoting characters. No such
quoting facility exists in ANSI~C, and experience shows that one is
generally better off without it. For example, the previous example is
better handled with the facilities of \FWEB\
by recalling that the macro processor is case-sensitive
while \Fortran\ is not, so one could simply say `\.{n = N}'.  However, in a
few situations quoting is necessary or convenient. For example, it is
difficult to include a comma unprotected by parentheses in a macro argument
without quoting it. Unfortunately, the number of special characters
available in \FWEB\ as candidates for quote characters is severely limited;
C~has usurped almost all of them (including brackets, in particular) for
its own purposes. Presently, in \FWEB\ one level of quoting can be
accomplished by 
enclosing the text that is not to be expanded with left single
quotes---for example, `\.{`N` = N}'. (This style of programming is
definitely not recommended.)  As another example, consider a C~example that
aborts by printing the name of a buffer that was overrun by a string print
operation.  The example defines a three-argument macro \.{SPRINTF}, whose
last argument is intended to actually be a comma-delimited \It{list} of
arguments.  Left quotes can be used to force that list to be treated as one
argument (although see the discussion of variable arguments below for a
better way).  The example also illustrates the stringizing operation and an 
appropriate usage of outer macros (explained below) vs.\ \WEB\ macros.
^^<macro!quoting>

{\codemode
@c
@
@d N 1000
@m SPRINTF(buf_name,nmax,args) 
\Tab if(sprintf(buf_name,args) >= nmax) overflow(#buf_name)
@A
char temp[N];

SPRINTF(temp,N,`"x = 0.2e\\n",x`);
}
\noindent In general, if you encounter a situation in which you think you
need to quote something, pause and think again; very often there's a better
way. 

\dsubsubsection Passing quoted strings unchanged through stringize.

As noted, when the single token `\Stringize' is followed by a macro
parameter, the parameter is made into a string. When `\Stringize' is
followed by something other than a macro parameter, other actions are
taken by \FWEB.

Sometimes you would like an existing quoted string to be
passed unchanged through the stringize operation. This can be accomplished
with the \.{\#*} operator.
^^:\>{\PM *}:
Thus, consider

{\codemode
@c
@* STRINGIZING REDUX.
@m S(s) #s
@m T(s) #*s
@A
S("hello"); // -> `"\\"hello\\"";'.
T("hello"); // -> `"hello";'.
@n
	S('hello') // -> '''hello'''.
	T('hello') // -> 'hello'.
}

\dsubsubsection Automatic statement numbering.

\parinserto{2}{4}{0.5}
``Numeric statement labels are unreadable anachronisms.''

For \Fortran\ programmers, 
the most important of the extensions is related to automatic statement
numbering.
^^[statement!numbering]
^^[Fortran:\FORTRAN!automatic statement numbering]
There are two distinct
possibilities, both begun by `\.{\#:}'.  ^^{\>{\PM":}}
The construction
`\.{\Stringize:0}' expands \It{at the time the definition is being stored}
(in phase one) to a unique statement number. That same number will be used
in all expansions of that macro throughout the program. Thus, it is
possible to completely abandon numeric statement labels in \Fortran\ simply
by ``declaring'' alphanumeric labels as \WEB\ macros, as in the following
example:

{\codemode
@n
@* STATEMENT LABELS.
@m START #:0
@m DONE #:0
@a
\Tab program main
START: continue
DONE: end
}
\noindent Note that alphanumeric labels must be followed by a colon, just
as in~C.  If you are a \Fortran\ programmer, \It{it is strongly encouraged
that you make use of this mechanism.} Numeric statement labels are an
unreadable anachronism.

If `\.{\Stringize:}' is followed by a positive integer~$n$, it expands into
a unique statement number (the current automatic statement number plus~$n$)
\It{at the time the macro is being expanded} (in phase
two). That number can appear more than once in the macro's replacement
text. It will expand into the same statement number during a given
expansion of the macro, but will generate a different unique number in each
subsequent expansion. This feature is useful in defining macros such as
error procedures that contain labelled code. For example,
^^<statement!numbering>

{\codemode
@n
@m CHECK(i,err_num) if(i >= 0) goto #:1;
\Tab\Tab call errprint(err_num);
\Tab\Tab\Tab return;
\Tab #:1 continue@;
}
\noindent (Of course, this particular example could have been accomplished
without statement numbers at all by using an \&{if}\dots\&{end if}
construction.) 

The starting value~\It{nnnnn} of the automatic statement number can be
set by the command-line option \hbox{`\.{-:\It{nnnnn}}'}.
^^{\>{-":}} ^^[statement!number!setting]
Any user statement
number must be less than that value. (\FWEB\ does not check that this
restriction is obeyed.)
Again, proper use of the `\.{\#:0}' and
`\.{\PM :}$n$' options should entirely eliminate the need for
explictly-defined user statement numbers in \Fortran.  \It{Note:}
Automatic statement numbers are not intended to replace \&{if}-, \&{case}-,
or~\&{do}-construct names in \Fortran--90.  For example, in the legitimate
\Fortran--90 construction

{\codemode
iterate: do
\Tab ...
end do iterate
}
\noindent the label \\{iterate} should not be declared as an automatic
statement number.

\dsubsubsection Preventing macro expansion.

Next, we have the ``don't expand'' option `\.{\#!}'.
^^:\>{\PM"!}: ^^[macro!preventing expansion of]
As stated earlier, usually
actual macro arguments are exhaustively expanded before they are
substituted into macro replacement text. To prevent this, preface a macro
parameter by `\.{\#!}'. Consider, for example,
^^<macro!preventing expansion of>

{\codemode
@c
@* PREVENTING MACRO EXPANSION.
@m A 1
@m S(s) #s
@m R(expr) S(expr)
@m Q(expr) S(#!expr)
@A
S(A) // -> `"1"'
R(A) // -> `S(1)' -> `"1"'
Q(A) // -> `S(A)' -> `"A"'
}

^^)macro!extensions)

\dsubsubsection Module names in macro definitions.

Occasionally one may want to include a module name as part of a macro
definition. The original design of \WEB\ precluded this possibility, since
encountering an \atcmd{<}~construction while in the definition section
signaled the start of a named code section. Therefore, within a macro
definition the special construction \.{\#<\dots@>} ^^{\>{\PM<...@>}}
may be used to represent a module name. Thus, you can make definitions such as

{\codemode
@m SHORTHAND #<First stuff@>@; #<Last stuff@>
}
\noindent Of course, you lose the readability of the module names in the
code proper if you do
things this way. Generally, the module name would be only a small part of a
much longer macro definition.

\dsubsubsection Macros with variable numbers of arguments.

^^[arguments!variable, in macros] ^^[macro!arguments!variable number of]
\parinserto{1}{4}{0.6}
{\ssbf WEB} macros may have a variable number of arguments.

We now discuss macros with variable numbers of arguments. These are
indicated by an argument list that ends with an ellipsis (\.{...}).
^^{ellipsis "(\noexpand\dots")} ^^{\>{...} "(ellipsis")}
Certain built-in functions such as
\\{\_IFCASE} accept a variable number of arguments. You can also define
them yourself, using some special tokens beginning with~'\.{\#}' to help.

The construction~`\.{\#0}' ^^:\>{\PM0}:
expands into the number of variable arguments (those arguments that replace
the ellipsis).  Note that an empty argument ^^{macro!arguments!empty}
is not the same as no arguments.  For example, \.{\#0}~counts as follows:

{\codemode
@m A(...) #0
@a
A => 0
A(x) => 1
A() => 1
A(x,y) => 2
A(x,) => 2
A(,y) => 2
A(,) => 2
}

The construction~`\.{\#$n$}', where $n > 0$, ^^:\>{\PM}$n$:
expands into the $n^{\rm th}$ variable argument (counting from~1).  

The constructions~`\.{\#\{0\}}' and~`\.{\#\{$n$\}}' are just like~`\.{\#0}'
and~`\.{\#$n$}' except that the argument inside the braces may be an macro
expression [anything that you could put inside \.{@\#if(\dots)}] that is
known at output time.  This is often useful in conjunction with the
\.{\_DO} built-in macro.  For example,

{\codemode
@n9
@
@m BFORALL(nmin,nmax,mmin,mmax,...) 
\Tab	forall(i=nmin:nmax,j=mmin:mmax) #\{I\}(i,j) = #\{I+1\}(j,i)
@a
_DO(I,1,6,2)
\Tab \{
\Tab BFORALL(1,5,0,20,v1,v2,v3,v4,v5,v6)
\Tab \}
}

The construction~`\.{\#[0]}' is just like~`\.{\#\{0\}}' except that it
counts the fixed arguments as well.  The construction~`\.{\#[$n$]}' is just
like~`\.{\#\{$n$\}}' except that the counting begins with the first fixed
argument.  Thus, in the above call to \\{BFORALL}, one has $\.{\#0} = 6$,
$\.{\#\{0\}} = 6$, $\.{\#[0]} = 10$, $\.{\#[2]} = 5$, and $\.{\#[6]} =
\.{\#\{2\}} = \.{v2}$. 

Finally, the construction~`\.{\#.}' ^^:\>{\PM.}:
expands into a comma-separated list of all the variable arguments.  

As examples,

{\codemode
@m V(x,y,...) x + y + f(#0,#.) + #3
@m V1(x,y,...) x + y _IFCASE(#0,,+g(#.))
@a
V(a,b,x1,x2,x3) => a + b + f(3,x1,x2,x3) + x3
V1(a,b) => a + b
V1(a,b,c) => a + b + g(c)
}
\noindent The \\{V1}~example shows that the conditional builtins can often
be used to advantage in conjunction with variable arguments.

We can use variable arguments to reconsider the previous example of the
\.{SPRINTF} macro:

{\codemode
@m SPRINTF(buf_name,nmax,...)
\Tab if(sprintf(buf_name,#.) >= nmax) overflow(#buf_name)
@a
char temp[N];
SPRINTF(temp,N,"x = 0.2e, y = 0.2g\\n",x,y); // 2 fixed args, 3 variable ones.
}
\noindent This works just fine.  However, a special feature of this example
is that valid syntax demands that there be at least one variable argument
(the string template).  Suppose instead we had defined

{\codemode
@m SPRINTF(buf_name,nmax,strng,...)
\Tab if(sprintf(buf_name,strng,#.) >= nmax) overflow(#buf_name)
}
\noindent Now there's potential difficulty when there are no variable
arguments.  For example, one might expect ``\.{SPRINTF(temp,N,"hello")}''
to expand to ``\.{if(sprintf(temp,"hello",) \dots}''; however, the missing
argument is invalid C~syntax.  Since this kind of construction seems to
arise fairly frequently, we have the following special \It{experimental}
rule: \It{if \.{\#.}~is empty and it immediately follows a comma in the
macro expansion, the comma is deleted.}  (Whether this is a good idea
remains to be seen. More elaborate alternatives are possible; complain if
you don't like this.) 

\dsubsubsection Debugging macros.

^^[macro!debugging]
If one wishes to debug an errant macro, there are several possibilities.
First, one could simply dump its current expansion into the output file.
For example,

{\codemode
@m DUMP(...) [#.]
@a
DUMP(A,B(1),C(x,y,z))
}
\noindent writes a comma-separated list of the expansions of three macro
calls, surrounded by brackets.  Alternatively, one can write information to
the terminal with the built-in function \.{\_DUMPDEF}.  The format is the
same as above; just replace \.{DUMP} by \.{\_DUMPDEF}.  For each macro call
in its argument list, \.{\_DUMPDEF} writes two lines.  The first is a
representation of the original macro definition; the second is its current
expansion.

\dsubsection Outer macros.

^^[macro!expansion!deferring]
\parinserto{2}{5}{0.45}
To defer macro expansion to an external preprocessor, use the `{\ssbf @d}'
command.

As we have said, \WEB\ macros are expanded by \TANGLE\ as it creates the
compilable output file during phase two. This means that the output file,
which is what you will actually be debugging, need not be very readable if
the macros were at all sophisticated (and, therefore, very useful). For
\Fortran\ programming, one has no choice. However, for C~programming it is
desirable to defer macro expansion to the C~preprocessor so that your
output file remains readable.  This can, of course, be done with no special
effort just by using the C~preprocessor \.{\#define} command ^^{\>{\PM define}}
as part of your code fragment. Usually, you should insert these in the code
section of the module in which they are first used so that the flow of the
logic is clearest.  However, what you usually really want is for your
preprocessor definitions to appear at the top of your file, no matter where
you actually defined them. (There are exceptions to this.) To help you
achieve this effect while maintaining logical clarity, the \WEB\ system
supports the concept of ``\It{outer macros}''. ^^:macro!outer:
These are defined by the command~\atcmd{d}, ^^{\>{@d}}
which is allowed in the definition section only. \WEB\ does not expand
these; rather, it just collects them and copies them at the start of phase
two to the beginning of the output file in a format appropriate for the
relevant language compiler.  For symmetry, the command~\atcmd{u} ^^{\>{@u}}
is also provided to undefine an outer macro.  

The format of outer macros depends on the language in force. If the current
language is~C, the outer macros should, of course, be in the format
appropriate to the C~preprocessor; an outer C~definition of the form
\atcmd{d A 1} will appear in the beginning of the C~output file as
`\.{\#define A 1}'.  Otherwise, the outer macro should be in the format
appropriate to the 
\.{m4}~preprocessor. In languages other than~C, the definition 
\atcmd{d (B,2)} will appear in the beginning of the output file as 
`\.{define(B,2)}'. (With the advent of \FWEB's macro processor, the need
for outer macro definitions in languages other than~C should virtually
disappear.)

For example, when the language is~C, the statements

{\codemode
@
@d A 1
@d B 2
\Par
@
@u A
@d A 2
}
\noindent will be output as follows:

{\codemode
#define A 1
#define B 2
#undef A
#define A 2
}

A C~program maintained with
\WEB\ should almost exclusively contain the outer macro,
\atcmd{d}~commands. The 
internal, \atcmd{m}~commands should be used only when the \WEB\ system
provides a 
macro feature not included in the C~preprocessor.  Those features mostly
include stringizing and token pasting (included in the ANSI C~standard, but
not in many extant compilers). If you are using an ANSI C~compiler, your
need for \WEB\ macros will be slight, although a few of the extensions such
as~\.{\#!} or variable arguments may prove useful.

\dsubsection Deferred macros.

Returning now to the internal \WEB\ macros, their order of evaluation
^^[macros!order of evaluation]
requires further discussion. It is important to understand that \It{all}
text, including macro definitions, is collected, tokenized, and stored
during \TANGLE's phase one. ^^{phase!1!\>{TANGLE}}
However, with certain exceptions (involving
the preprocessor) to be described, \It{no macros are actually expanded
during phase one}. The reason for this is that the actual source text in
which the macros are embedded and on which they must operate is not known
until all the text has been collected and placed into the proper modules.
Therefore, it is during phase two, when the completed code text is output,
that macros are expanded. However, in the original design of \WEB\ this led
to an annoying difficulty---namely, \WEB\ macro definitions could be
\It{retroactive}. 

^^[macro!retroactive definition of]
The situation arises as follows.  In the original design, macros were
allowed only in the definition section of a module. Since all such macros
definitions are collected during phase one, they are all known by the time
code is output during phase two.  (Effectively, they are all placed at the
top of the unnamed module.)  Thus, a definition made in the definition
section of, say, module~100 could lead to a macro being expanded in module~1
if the code in module~1 contained a reference to that macro name. Although
this is usually the desired effect, it may not be in all cases. 
Consider, for example, the following example (see the discussion of
preprocessor commands, below):

{\codemode
@ Here is a peculiar example of retroactive macro definition.
@m A 1
\If(A==1)
\Tab x = A;
\Else
\Tab x = B;
\Endif
\Par
@ Another section.
@m A 2
.
.
}
\noindent Here the generated code will be ``\.{x = 2;}'', not ``\.{x = 1}'' or
``\.{x = B;}''.  Note also that since the sections, hence the definition
parts, are not required to appear in any particular order, 
the order of encountering \WEB\ macro definitions is somewhat indefinite.
This can lead to confusion and hard-to-understand bugs if macros are
redefined and sections are subsequently moved around.

\parinsert{6}{5}{0.5}
Don't define {\ssbf WEB} macros in the code part unless you absolutely
have to.

For complete flexibility, therefore,  \FWEB\ introduces the
notion of \It{deferred macros}. ^^:macro!deferred:
Deferred macros are nothing more than \WEB\ macros defined (again
with~\atcmd{m}) in the \It{code} section rather than in the definition section. A deferred macro definition, although it is stored away in a safe place
during phase one, becomes known to the \WEB\ macro processor only at the point
in the code where the definition is made, when the code is being output
during phase two.  Thus, the order in which the deferred macro definition
is made is unambiguous (it is determined by the intrinsic structure of the
code, not by the order in which things were explained) and the deferred
definition cannot be inadvertently expanded retroactively.  Remembering the
previous discussion of C~preprocessing, we see a complete analogy: deferred
\WEB\ macros are analogous to the use in~C of
\.{\#define}; both are used in the code section. All definitions made in
the definition part behave similarly in that they are placed at the
beginning of the appropriate place: outer macro definitions (\atcmd{d}) are
placed at the beginning of the output file; \WEB\ macro definitions in the
definition part (\atcmd{m}) are effectively placed at the beginning of the
unnamed module. 

Most of the time, it will be adequate to define a \WEB\ macro in the
definition part, thereby placing it at the beginning of the unnamed
module, and it is recommended that you do so whenever possible. Reserve
deferred macro definitions for those relatively rare instances when the
order of defining the macro really does matter.

Although deferred \.{@m}~commands work as specified, presently
preprocessor commands (see below) such as~\.{@\#if} or~\.{@\#undef} do not
work as one might expect when referring to deferred macros. Presently, such
commands are executed during phase one (on input), whereas the deferred
macros become known only during phase two (on output).  Luckily, there is
an an alternative way of handling preprocessing during output, namely to
use built-in functions such as \.{\_IF}.
^^{\>{\UL IF}}
See the discussion of built-ins below.

\dsubsection Language dependence of macros.

\WEB\ macros are by and large not sensitive to language when they are being
memorized, and with a few exceptions they will expand in the same way no
matter what language is current during output. (An example of an exception
is the behavior of the stringizing operation, which must build a string
using either a single or double quote depending on the language. Another
example is the \.{\_ROUTINE} built-in function ^^{\>{\UL ROUTINE}}
which at presently is defined only for
\Ratfor.)  Generally such uniform expansion is desirable. For example,
here is how one can supply a macro definition in~C and a \&{parameter}
statement in
\Fortran\ with a common value:

{\codemode
@n
@ Web macros are known to all languages.
@m NN 100 // One can affect all languages by changing this one number.
@c
@d N NN
@A
\Tab parameter(N=NN) // A fragment of a Fortran code.
@c
@<C functions@>@;

@ A simple C routine.
@<C...@>=
f()
\{
return N;
\}
}
\noindent If language-sensitive behavior is desired, it can be achieved by
using the \.{\_LANGUAGE} built-in function ^^{\>{\UL LANGUAGE}}
in conjunction with an \.{\_IFELSE}, or the \.{\_LANGUAGE\_NUM} built-in
^^{\>{\UL LANGUAGE\UL NUM}} in conjunction with an \.{\_IFCASE}. See further
discussion below. 

\parinsert{2}{5}{0.45}
{\ssbf WEB} macros can be defined from the command line with the option
`{\ssbf -m}'.

\WEB\ macros can also be defined from the command line by using the
command-line option `\.{-m}'. ^^:\>{-m}:
(See the detailed explanation in the section about command-line options.)
Command-line macros are processed at the beginning of the first definition
section. Defining macros from the command line is an efficient way to
customize a code without re-editing it. For example, you can supply fixed
array bounds to a \Fortran\ program employing one of the two equivalent
statements 
^^<\>{-m}>

{\codemode
FTANGLE test -mN=1000
FTANGLE test -m"N 1000"
}
\noindent which is equivalent to saying \atcmd{m N 1000} at the beginning of
the first definition section,
then including statements such as `\.{integer x(0:N)}' in your code. 
The facility is
particularly useful in conjunction with the \FWEB\ preprocessor, to be
described next. 
^^)macros)

\vfill\Eject

\dsubsection Preprocessing. ^^(preprocessing( ^^(preprocessor!\FWEB(
^^[language!preprocessing] ^^[macro!preprocessing]

A common situation arises when one is designing a code to run on more than
one machine. One might want to define a macro with machine-dependent
values, or one might want to selectively include one or another piece of
code.  In addition to macro definitions, \WEB\ has a complete preprocessing
language to help in this respect.

\parinsert{1}{5}{0.4}
``The {\ssbf WEB} preprocessor is patterned after that for ANSI~C.''

The \WEB\ preprocessor is patterned after that for ANSI~\C. All
preprocessing commands begin with~`\.{\PR}'. As in ANSI~C, they need not,
in general, begin in in column~1 (they must do so, at present, in \Fortran's
fixed-format mode). Unlike
ANSI~C, 
however, there may be no white space between~`\.{\PR}' and the command
name.  (\WEB\ interprets an isolated~`\.{\PR}' as a command to insert a blank
line.)  In~C and
\Ratfor\ they may be continued to subsequent lines by using a backslash; in
\Fortran, they are presently restricted to
end on the same line (including any optional comment). They are

{\narrower\parskip=0pt\medbreak\obeylines
\Define\ \It{macro\_name} \It{replacement\_text} 
\Undef\ \It{macro\_name} 
\Ifdef\ \It{macro\_name}
\Ifndef\ \It{macro\_name}
\If\ \It{expression}
\Elif\ \It{expression}
\Else
\Endif

}
\noindent The `\Define' command ^^:\>{@\PM define}:
is entirely equivalent to~\atcmd{m}. One can undefine a macro definition
with `\Undef'. ^^:\>{@\PM undef}:
(All previous definitions are completely lost; definitions
are not stacked.)  `\Ifdef' and `\Ifndef' test whether a macro is or is not
defined. ^^:\>{@\PM ifdef}: ^^:\>{@\PM ifndef}:
(These commands are special cases of~`\.{\If}'; see the discussion
of the `\.{defined}' operator below.) The
`\If\dots\Elif\dots\Else\dots\Endif' construction 
^^:\>{@\PM if}: ^^:\>{@\PM elif}: ^^:\>{@\PM else}: ^^:\>{@\PM endif}:
evaluates
\It{expression}, which must consist of symbols known to the preprocessor at
the current point of the input scan, then takes action depending
on whether \It{expression} ^^{expression!logical}
is true (nonzero) or false~(0).  All
preprocessing commands may appear in either the definition part or the
code part. In the definition part, \FTANGLE\ will not process macro
definitions that are between the false part of the preprocessor
conditionals.  In the code part, \FTANGLE\ will not store or output code
that is between the false part. The conditionals may be nested.\filbreak

\It{Note that all preprocessor commands, including in particular those in
the code section, are expanded during phase one.}
^^{phase!1}
This is a design flaw (maybe it will be corrected someday) that
means that the preprocessor commands will not work correctly with deferred
macros, 
^^{macro!deferred}
which become known only during phase two. ^^{phase!2}
If you need to use
deferred macros with preprocessor commands, use the built-in forms of the
preprocessor commands such as \.{\_IF}. Built-ins are discussed below.

Use of the \WEB\ preprocessor is entirely analogous to that of~C. If you
are a C~programmer, you will need the \WEB\ preprocessor commands
relatively rarely; operations on your source code are usually better done
with the C~preprocessor. If you are a \Fortran\ programmer, however, you
should find the preprocessor facility extremely useful.

It is conventional to end long preprocessor constructions as follows, to
enhance the quality of the documentation:

{\codemode
@#if(CRAY)
\dots
@#endif // |CRAY|
}

\vfill\Eject
^^[expression!evaluation]
\dsubsection Expression evaluation. ^^{macro!expression evaluation}

The \It{expression} in constructions such as \If~\It{expression} is
evaluated by a built-in expression evaluator that can also be used for
other purposes, such as in macro expansion.  Its behavior is again
motivated by expression 
evaluation in ANSI~C; it is not quite as general, but should be more than
adequate. It supports both integer and floating-point arithmetic (with type
promotion from integer to floating-point if necessary), and the ANSI
`\.{defined}' operator. Operators with the highest precedence 
^^{operators!precedence of}
(see table below) are evaluated first; as usual, parentheses override the
natural order of evaluation. The unary operator `\.{defined}' 
^^{\<{defined}, as unary operator}
has the highest
precedence; all the other unary operators have the next highest (and equal)
precedence; then come the binary operators. When the operator exists in~C,
the action taken by \FWEB\ is precisely that that the C~compiler would take.
Arithmetic is done in either \&{long} or \&{double} variables, as
implemented by the C~compiler that compiled \.{FTANGLE}.  (This was the
easy choice, not necessarily the most desirable one.)

^^[expression!operators] ^^[operators]
The operators, listed from  highest precedence  to lowest, are as follows:
$$\def\<{{\rm ,$\,$}}
\def\mod{\Mathop{mod}}
\vtop{\halign{\tt\quad#\quad\hfil&\ ---\
\vtop{\hsize=0.75\hsize\noindent\hang \strut#\strut}\hfil\cr
\noalign{\medskip\leftline{\hl{Unary operators}:}\smallskip}
defined&^^:\>{defined}: `\.{defined}'  is a unary operator that acts on
identifier tokens. 
`\.{defined id}' or equivalently `\.{defined(id)}' evaluates to~1 (true) if
the identifier is defined as a \WEB\ macro; 
to~0 (false) otherwise.  The construction `\.{\If{ }defined A}' works the
same way as
\.{\Ifdef{ }A}, but you can use `\.{defined}' in expressions, as in
$$
\hbox{\.{\If{ }defined(A) || defined(B)}}.
$$ 
(The parentheses around the macro names are optional.)
With the advent of `\.{defined}', the
\WEB\ preprocessor statements \Ifdef\ and \Ifndef\ become redundant, but
are often useful shorthands.\cr
-&Unary minus.\cr
!&^^:\>{"!}: Logical \hbox{\.{NOT}}. \.{!\expr} evaluates to~0 if \.{\expr}
is nonzero, and evaluates to~1 if \.{\expr} is~0.\cr
\TL&^^:\>\TL: One's complement of an integer. For example, $\.{\TL0} =
-1$.\cr 
\noalign{\medskip\leftline{\hl{Binary operators}:}\smallskip}
\^\^&^^:\>{\^\^}: Exponentiation (all languages). $2\hbox{\.{\^\^}}3 = 8$.\cr
\^\<**&^^:\>\^:^^:\>{**}: Exponentiation (\Fortran\ or \Ratfor).\cr
*\</\<\%&^^:\>\PC: Multiplication, division, and modulus: 
\.{$a$ \% $b$} means $a \mod b$; for example, \.{5 \% 3 = 2}. \cr
+\<-&The usual plus and minus.\cr
<<&^^:\>{<<}: \.{$a$ << $b$} means shift integer~$a$ left $b$~bits. $1 \ll
3 = 8$.\cr
>>&^^:\>{>>}:  As above, but right-shift. $7 \gg 2 = 1$.\cr
<\<<=\<>\<>=&Evaluates to~1 if the inequality holds, to~0 otherwise.
E.g., \.{(2.0 < 3.0)} evaluates to~1.\cr
==\<!=&^^:\>{==}: \.{$a$==$b$} (\.{$a$!=$b$}) evaluates to~1 (0) if $a$
equals~$b$; evaluates to~0 (1) otherwise.\cr 
\amp&^^:\>\amp: Bitwise \hbox{\.{AND}}. The truth table is \.{0b1100 \amp{
}0b1010 = 0b1000}.\cr 
\^&^^:\>\^: Bitwise \.{EXCLUSIVE OR} (C). (For \Fortran, use `\.{.xor.}'.)
The truth 
table is {\.{0b1100}~\.{.xor.}~\.{0b1010 = 0b0110}}.\cr
|&^^:\>{"|}: Bitwise~\hbox{\.{OR}}. The truth table is \.{0b1100 | 0b1010 =
0b1110}.\cr 
\amp\amp&^^:\>{\amp\amp}: Logical~\hbox{\.{AND}}.\ \.{$a$ \amp\amp{ }$b$}
evaluates to~1 if both~$a$ and~$b$ are true (nonzero).\cr 
||& Logical~\.{OR}. \.{$a$ || $b$} evaluates to~1 if either~$a$ or~$b$
are true.\cr 
  }}$$
Note in particular the use of the single caret, which is
language-dependent:  it is an 
exponentiation operator for \Fortran\ (just as in \TeX), but the
\.{EXCLUSIVE OR} operator for~\C. Also, note that the bitwise operators
should almost never be used. For 
logic, almost always you will be using~\.{==}, \.{!=}, \.{\&\&},
and~\.{||}. 

The preprocessor commands are ``active'' only for \FTANGLE. \FWEAVE\ will
format them in a reasonable way, but you can't, for example, comment out
some active \WEAVE\ operation such as~\atcmd{f} with `\If\dots\Endif'.
Furthermore, you can't use preprocessor commands to comment out the
\atcmd{i}~include statement. (Include statements are processed by the input
driver, so the \atcmd{i}~command never gets to the innards of the \WEB\
processors.  A single \atcmd{i}~command can be commented out with~\atcmd{\%},
since \atcmd{\%}~is also processed by the input driver.)

Here are some suggested uses for the preprocessing facility. To comment out
code, say
^^<language!preprocessing>

{\codemode
\If(0) // You can also say ``\If\ 0''.
\Tab code // This text will not appear in the tangled output.
\Endif

}
\noindent To conditionally define a macro, say something like
^^<macro!conditionally defining>

{\codemode
@m CRAY // You might define this macro from the command line.
\Par
\Ifdef\ CRAY
\Tab @m CRAY 1
\Tab @m VAX 0
\Else
\Tab @m CRAY 0
\Tab @m VAX 1
\Endif\ // |defined CRAY|
\Par
\If\ CRAY
\Tab @m INIT cray\_code
\Else
\Tab @m INIT vax\_code
\Endif\ // |CRAY|

}
\noindent To conditionally select a block of code, say something like
^^<code!conditionally selecting>

{\codemode
\Tab program main
\Ifdef\ CRAY
\Tab @<Cray stuff@>
\Else
\Tab @<Vax stuff@>
\Endif\ // |defined CRAY|
\Tab end
}

^^)preprocessor!\FWEB) ^^)preprocessing)

\dsubsection Built-in macro functions.[7.7.19] ^^(macro!built-in(
^^(built-in!macros( 

\parinserto{2}{4}{0.5}
``{\ssbf FWEB} contains a small number of built-in functions.''

In certain circumstances a macro function is desired that cannot be
accomplished by a user definition, or is so ubiquitous that it seems useful
to save the user the trouble of defining it himself. Therefore, for
enhanced flexibility, \FWEB\ contains a small number of \It{built-in}
functions.  Each of these functions begins with an underscore and is fully
in upper case.  These functions behave just like \WEB\ macros.  Therefore,
\It{do not define any macros of your own that begin with underscores,} even
if they don't correspond to the name of a built-in function.  This restriction
is intended to prevent conflict with certain auxiliary macros used
internally by \WEB\ in the course of expanding its built-ins.  

The following list describes the built-in functions in a (somewhat) logical
order.  They are summarized alphabetically in Appendix~L.

\dsubsubsection {\tt \_EVAL}.

The built-in function \.{\_EVAL} ^^:\>{\UL EVAL}:
evaluates its argument using the preprocessor
expression evaluator described above. (If an error is encountered during
the evaluation, a message is printed and the argument is returned without
any evaluation.) For example,
^^<\>{\UL EVAL}>

{\codemode
@m A 2
@m B 3
@A
_EVAL(defined A \amp\amp\ defined(B)) // `1'
_EVAL(A + 5.0*B) // `17.0' (Note the promotion to floating point.)
_EVAL(A==B) // `0'
_EVAL(A==1 || A==2) // `1'
_EVAL(x) // `x'
array[_EVAL(B+1)] // `array[4]'
}
  
\noindent The last example above shows a common usage of \.{\_EVAL},
namely in providing more readable tangled code. That is, although many
C~compilers accept the construction \.{array[3+1]}, in some circumstances
it may be more meaningful to see \.{array[4]} while you're debugging.

\dsubsubsection {\tt \_DEFINE, \_M, \_IFDEF, \_IFNDEF, \_UNDEF}.

A built-in form of deferred macro definition is achieved via \.{\_DEFINE}
or~\.{\_M}.
^^:\>{\UL DEFINE}: ^^:\>{\UL M}:
These two names are synonyms; they are used by enclosing in parentheses all
the text that would normally follow an~\atcmd{m}, such as

{\codemode
_M(N\SP 5) // Equivalent to `@m N 5'.
_M(X(a,b) ((a)-(b)))
}
\noindent A subtlety occurs with a definition of the form 
``\.{\_M(foo\ (bar))}''.  Because spaces are removed early in the
tokenization process, this definition is equivalent to ``\.{@m foo(bar)}''
(a one-argument macro with null replacement text) instead of what one
probably intended, ``\.{@m foo\ (bar)}'' (a zero-argument macro).  To get
the latter effect, say ``\.{\_M(foo=(bar))}''.

The companion macros \.{\_IFDEF}, \.{\_IFNDEF}, and \.{\_UNDEF}
are also provided.
^^:\>{\UL IFDEF}: ^^:\>{\UL IFNDEF}: ^^:\>{\UL UNDEF}:
The syntax of the first two is, e.g,
\.{\_IFDEF(id,\truetext,\falsetext)}.  
Remember, these are macros, so their arguments must be enclosed in
parentheses---e.g., \.{\_UNDEF(X)}.

\dsubsubsection {\tt \_DO}.

A powerful means of \It{repetitively} defining a macro is provided
by~\.{\_DO}. ^^:\>{\UL DO}:
The syntax is 

{\codemode
_DO(I,Imin,Imax\It{[},dI\It{]})
\{
\It{text}
\}
}
\noindent This command is \FWEB's version of the \Fortran\ \&{do}~loop. It
behaves as though one said ``\&{do} $I=Imin,Imax\It{[},dI\It{]}$
\.\{\It{text}\.\}'', where the equals sign means a macro definition.  The
loop index should not be used as a \WEB\ macro for any other purposes,
since its previous definition will be destroyed.

(For symmetry, there ought to be a {\tt \_FOR} statement, but that's not in
place yet.)

\dsubsubsection {\tt \_INCR, \_DECR}.

The macros \.{\_INCR} and \.{\_DECR}
^^:\>{\UL INCR}: ^^:\>{\UL DECR}:
increment or decrement by~1 a macro that expands to a number. For example,
if the \WEB\ macro~\.{N} expands to~\.5, then \.{\_INCR(N)} redefines~\.N
to be~\.6. These are included for convenience; they are defined in terms of
\.{\_M} and \.{\_EVAL}.

\dsubsubsection {\tt \_IF}.

The conditional \.{\_IF(expr,\truetext,\falsetext)} ^^:\>{\UL IF}:
expands to
\.{\truetext} if \.{expr} is true, or to \.{\falsetext} otherwise. \It{Note
that in almost all situations the preprocessor commands
\.{\If}\dots\.{\Else}\dots\.{\Endif} provide a better, more readable
alternative to \.{\_IF}; use this built-in only as a last resort.} One case
in which you must use \.{\_IF} is when \.{expr} contains a deferred macro.

\dsubsubsection {\tt \_ABS, \_MAX, \_MIN}.

A few other constructions built out of \.{\_IF} have been included for
convenience: \.{\_ABS(a)}, \.{\_MAX(a,b)}, and \.{\_MIN(a,b)}.
^^:\>{\UL ABS}: ^^:\>{\UL MAX}: ^^:\>{\UL MIN}:

\dsubsubsection {\tt \_IFCASE}.

The \.{\_IFCASE} macro 
^^:\>{\UL IFCASE}:
provides conditional evaluation based on the value
of a control integer. It is analogous to \TeX's \.{\\ifcase} macro or to
\Fortran's computed \&{goto}. The format is

{\codemode
_IFCASE(m,case_0,case_1,\dots,case_n,default)
}
\noindent Here $m$~is an
expression that evaluates to an integer in the range $0 \le m \le n$, and
the macro expands into the text \.{case\_m}. If $m$~is not in the above
range, then the default text is returned. (This is an example of a macro
that uses a variable number of arguments.)

\dsubsubsection {\tt \_IFELSE}.

The \.{m4}-like conditional
\.{\_IFELSE(macro1,macro2,\truetext,\falsetext)} ^^:\>{\UL IFELSE}:
expands each of \.{macro1} and \.{macro2}, then does a character-by-character
comparison. If the results are identical, \.{\truetext} is returned,
otherwise, \.{\falsetext} is returned. \It{Whenever possible use
\.{\If} instead.} Again, if \.{macro1} or \.{macro2} involve a deferred
macro, you must use \.{\_IFELSE}.

\dsubsubsection {\tt \_LEN}.

The macro \.{\_LEN(s)} ^^:\>{\UL LEN}:
interprets its argument as a character string
(without expanding it if it is a macro) and returns the length of that
string. For example, if you say
`\atcmd{m N 56}', then \.{\_LEN(N) -> 1}. Note that the string does not need to
be in quotes; that's done for you.  As a more complicated example, here's
one way to create a self-counted Hollerith string:

{\codemode
@m HOL(s) _LEN(#!s)##H###!s // HOL(abc) -> `3Habc'
}
\noindent Note that we had to be alert for the possibility that the
argument to \\{HOL} might inadvertently be a macro name, so we prevented
expansion with the \.{\#!}~operator.

\dsubsubsection {\tt \_POW}.

The exponentation macro \.{\_POW(x,y)}, ^^:\>{\UL POW}:
which expands~$x$ and~$y$ and returns~$x^y$,
is included for convenience; it is equivalent to \.{\_EVAL((x)\^\^(y))}.

\dsubsubsection {\tt \_TRANSLIT}.

The macro \.{\_TRANSLIT(s,from,to)} ^^:\>{\UL TRANSLIT}:
interprets each of its arguments as
strings (without expanding anything). Then $s$~is modified by replacing any
of the characters found in \\{from} by the corresponding characters
in~\\{to}. If \\{to} is shorter than \\{from}, then the excess characters in
\\{from}  are
deleted from~\\{s}. As a limiting case, if \\{to}~is empty, then all the
characters in \\{from} are deleted from~\\{s}. For example,
\.{\_TRANSLIT({\it s},aeiou,12345)} replaces the vowels in~\\{s} by the
corresponding digits, and \.{\_TRANSLIT(s,aeiou,)} deletes all the vowels.
The backslash may be used to escape a character, as in ANSI~C.  For
example,
\.{\_TRANSLIT("a\\"\\\\d","d\\\\a\\"","D,A'")} translates into~` \.{A',D}'.
Here we had to explicitly enclose strings involving '\.{\\"}' in double
quotes in order to avoid a complaint about an unterminated string.

\dsubsubsection {\tt \_A}.

The macro~\.{\_A} ^^:\>{\UL A}:
is the built-in equivalent of the~\.{@'} or~\.{@"} command.  
^^{\>{@'}} ^^{\>{@""}}
The construction~\.{\_A('x')} functions essentially the same as
the command~``\.{@'x'}'', and ``\.{\_A("xyz")}'' is essentially the same
as~\.{@"xyz"}.  (We say ``essentially'' because the \.{@'} and~\.{@"}
commands are expanded on input, whereas the built-in function~\.{\_A} is
expanded on output.)  The need for such a built-in is evident from the
following example, in which the quantity to be converted to ASCII is
constructed via macro expansion:
^^<\>{\PM'}>

{\codemode
@m OCTAL(n) OCTAL0(\\@&n)
@m OCTAL0(n) _A(#'n) // \.{OCTAL(123)} -> _A('\\123') -> 0123.
}
\noindent
Here one couldn't say something like ``\.{@m OCTAL(n) @'n'}'' for two
reasons:  first, \.{@}~commands are expanded on input; second, the
$n$~parameter wouldn't be expanded because it's inside a quoted string.
(Do you understand the function of the \.{@\&}~command in the definition of
\\{OCTAL}?)

\dsubsubsection {\tt \_STRING}.

The macro \.{\_STRING(macro)} ^^:\>{\UL STRING}: expands its argument, then
makes a string out of it (using the \.{\#*}~operator).
^^{\>{\PM*}}
That is, it provides
one extra level of expansion over the basic stringize operation.  Compare,
for example, the following expansions:

{\codemode
@c
@m A 1
@m S(s) #s
@A
S(A) // `"A"'
_STRING(A) // `"1"'
}

\noindent This macro is included for convenience, as the user can define it
himself. 

\dsubsubsection {\tt \_UNQUOTE}, {\tt \_P}.

For certain special effects, one has the \.{\_UNQUOTE} built-in function
(formerly called ``\.{\_VERBATIM}''). ^^:\>{\UL UNQUOTE}: ^^{\>{\UL VERBATIM}}
If one says
``\.{\_UNQUOTE("}\It{string}\.{")}'', the macro returns \It{string} without
the surrounding quotes. For example, this provides a way of getting the
special character~'\.\#' into the output from within a macro. For example,
the following macro creates C~preprocessor keywords:

{\codemode
@m PP(keyword) _UNQUOTE("#")##keyword
}
\noindent For the user's convenience, the macro~\.{\_P} ^^:\>{\UL P}:
is a synomym for
\.{\_UNQUOTE("\#")}. However, there is a subtlety here. Do you understand
why if one says

{\codemode
@m QQ(keyword) _P##keyword
}
\noindent one gets the following?

{\codemode
PP(define) // -> `#define'
QQ(define) // -> `_Pdefine'
}
\noindent To answer this question, carefully study the rules about macro
expansion and pasting. The proper way of defining~\\{QQ} is to
protect~\.{\_P} with left quotes:

{\codemode
@m QQ(keyword) `_P`##keyword
}

\dsubsubsection {\tt \_L}, {\tt \_U}.

Occasionally it is useful to change the case of a string parameter to a
macro.  This can be accomplished by means of the built-in functions~\.{\_L}
(change argument to lower case) and~\.{\_U} (change to upper case).  The
arguments to these functions must be quoted strings; they return the
case-converted string, also quoted.  For example, ``\.{\_L("ABC")}''
returns~``\.{"abc"}''. 

\parinsert{2}{4}{0.65}
The built-in functions `{\ssbf \_L}' and `{\ssbf \_U}' change the case of
their arguments.

An application in which such actions might be useful concerns mixed
programming in~C and \Fortran.  Suppose that in one's C~program the
\Fortran\ functions to be called had been distinguished by writing them in
upper case.  The code is supposed to be portable, and on at least one
machine the case-sensitive linker understands things just as they are.
However, suppose that on some other machine the \Fortran\ library was
compiled by a compiler that produced lower-case names---and, for good
measure, had appended an underscore to the name.  (This is precisely what
happens on Sun workstations.)  Here is how to macro up the situation to
make everyone happy:

{\codemode
@c
@ In the \\WEB\\\ program \\Fortran\\\ functions will be in upper case, 
C functions will be in lower case.
@#if VAX
\Tab @m F(name) name
@#else
\Tab @m F(name) _UNQUOTE(_L(#name))##_ // Stringize, convert to l.c., 
\Tab\Tab\Tab\Tab remove quotes, append '_'.
@#endif
@a
cfcn();
F(FORFCN)(); // Either |FORFCN()| or |forfcn_()|, depending on machine.
}

\dsubsubsection {\tt \_COMMENT}.

The macro \.{\_COMMENT(string)} ^^:\>{\UL COMMENT}:
generates a comment in the output file.
This is useful for macro definitions in which comments are desired; the
usual C-style comments are stripped off as the definition is being
absorbed. Thus, in~C, the definition 
\atcmd{m TEST a;\_COMMENT("Hello,\ world")b;} expands into 
`\.{a;/*\ Hello,\ world\ */b;}'. Note that the
\.{string} argument must be in quotes. (Actually, this is essential only
when the argument contains commas; otherwise, the commas will be
interpreted as argument delimiters and an error message about the wrong
number of arguments will ensue. However, it is good practice to always use
the quotes.) If you had wanted the comment to be on a separate line, you
could have inserted newlines into the string, as in
\.{"\\nHello,\ world\\n"}. In \Fortran, the comment is automatically put on
a separate line.

\dsubsubsection {\tt \_ASSERT}.

Error mechanisms are provided by several macros, \.{\_ASSERT} and
\.{\_ERROR}.  The \.{\_ASSERT(\expr)} ^^:\>{\UL ASSERT}:
macro evaluates \.{\expr}. If that expression is false, an error message is
sent (to both the terminal and the output file) and processing is aborted
immediately. This feature, motivated by ANSI~C, is intended to help one
verify certain conditions that must be true in order for processing to
proceed. For example, suppose you always intended to define the macros
\\{N1} and~\\{N2} from the command line. To make sure you didn't forget,
you could say at the beginning of your code

{\codemode
\_ASSERT(defined N1 && defined N2)
}

Like all of the built-ins, \.{\_ASSERT} is expanded on output, during
processing of the \It{code part}.  It will have no affect if it appears in
the definition part.

\dsubsubsection {\tt \_ERROR}.

The \.{\_ERROR(string)} ^^:\>{\UL ERROR}:
macro sends \.{string} to the standard error message
facility, but does not abort. Thus, \.{\_ERROR("That didn't work")}
generates an error message giving the line number and the file in which the
macro was expanded. Note that the \.{string} argument must be in quotes.

\dsubsubsection {\tt \_DUMPDEF}.

The \.{\_DUMPDEF} built-in is used for debugging \WEB\ macros. 
^^:\>{\UL DUMPDEF}: 
It takes an arbitrary number of macro calls, separated by commas, as in

{\codemode
_DUMPDEF(A,B(1),C(x,y,z))
}
\noindent where it is assumed that~$A$, $B$, and~$C$ are macros with~0, 1,
and 3~arguments, respectively.  For each
macro, two lines are written to the terminal.  The first is a
representation of the original macro definition, the second is the
expansion.

\dsubsubsection {\tt \_LANGUAGE}, {\tt \_LANGUAGE\_NUM}.

The two built-in functions \.{\_LANGUAGE} and \.{\_LANGUAGE\_NUM}
^^:\>{\UL LANGUAGE}: ^^:\>{\UL LANGUAGE\UL NUM}:
provide ways of endowing a \WEB\ macro with a language attribute.
The \.{\_LANGUAGE} macro expands into an \It{identifier}
(\It{not} a macro, unless you define it yourself) such as~`\.{\_C}'.  (See
the table below.)  It is
intended to be used in an  \.{\_IFELSE} statement.  The \.{\_LANGUAGE\_NUM}
macro expands into an integer (see the table below) and is intended to be
used as the first argument to an \.{\_IFCASE}.
\LANBUILTINS
For example, here is a way of defining a macro to be
the ``natural'' lower array index in either of~C or \Fortran, assuming that
one programs in only those two languages.

{\codemode
@m LOWER _IFELSE(_LANGUAGE,_C,0,1)
}
\noindent If you also sometimes use~\Cpp, however, you need a three-way
switch; the simplest way of achieving that is to use \.{\_LANGUAGE\_NUM}:

{\codemode
@m LOWER _IFCASE(_LANGUAGE_NUM,0,0,1)
}
\noindent This macro still isn't ideal, however.  It returns an explicit
value for the languages~C, \Cpp, and \Fortran--77, but would return nothing
for any other language.  If you started to use \Fortran--90 someday, you'd
get into trouble, and this kind of error can be hard to track down.  It's
best to be very explicit:

{\codemode
@m LOWER _IFCASE(_LANGUAGE_NUM,0,0,1,1,1,1,0)
}

\ddsubsubsection {\tt \_STUB}.

If a reference to an undefined module is encountered, it is replaced
automatically by a call to the built-in
\.{\_STUB}, with the module name as argument.  
^^:\>{\UL STUB}:
The form of the call is
language-dependent.  Thus, if the module \.{@<Absent@>} is never defined,
then a reference to \.{@<Absent@>} will tangle to the
expansion of ``\.{\_STUB(Absent)}'', which in~C is by default
``\.{\{missing\_mod("Absent");\}}''.  In \Fortran, the same reference would
tangle to ``\.{call nomod('Absent')}''.  If you don't like the default
actions, you can redefine \.{\_STUB} yourself with~\.{@m}.  The purpose of
this macro is to help one compile and debug a code that is not fully
developed. 

\dsubsubsection {\tt \_GETENV}, {\tt \_HOME}.

The built-in \.{\_GETENV(}\\{ENV}\.{)} ^^:\>{\UL GETENV}: ^^:\>{\UL HOME}:
 returns the value of the environment variable~\\{ENV}, 
^^{variable!environment}
using the C~library call \\{getenv}.  The built-in
\.{\_HOME} is equivalent to \.{\_GETENV(HOME)}.

\dsubsubsection {\tt \_VERSION}.

The built-in \.{\_VERSION} ^^:\>{\UL VERSION}:
expands into a string containing the \WEB\ version number, such as~\.{"1.13"}.

\dsubsubsection {\tt \_MODULE\_NAME, \_SECTION\_NUM}.

^^:\>{\UL MODULE\UL NAME}: ^^:\>{\UL SECTION\_NUM}:
Two built-ins provide information about where one presently in the web.
\.{\_MODULE\_NAME} expands to the name of the current module that is being
expanded; \.{\_SECTION\_NUM} is the number of the current section.

\dsubsubsection {\tt \_MODULES, \_SECTIONS}.

^^:\>{\UL MODULES}: ^^:\>{\UL SECTIONS}:
Two built-ins provide some statistics about the structure of the program
being tangled or woven. \.{\_MODULES} expands into an integer that is the
total number of \It{independent} module names, plus~1 for the unnamed module.
\.{\_SECTIONS} expands into the maximum section number, as \WEAVE\ would
compute it. These numbers could be used as array bounds for various
esoteric purposes. For an example of the use of these macros, see the demo
program \.{breakpt.web}.

\dsubsubsection {\tt \_DATE, \_DAY, \_TIME}.

Finally, there are various date and time macros that expand into strings
containing the relevant information: \.{\_DATE}, \.{\_DAY}, and \.{\_TIME}.
^^:\>{\UL DATE}: ^^:\>{\UL DAY}: ^^:\>{\UL TIME}:
These macros are intended primarily for internal use; they are used in
generating the comments output at the beginning of the tangled output and
at the end of the woven output.  However, they are available to the user as
well. These macros expand as follows:

$$\vbox{\halign{\.{#}\hfil&\ $\to$\ \.{"#"}\hfil\cr
\_DATE&August 15, 1989\cr
\_DAY&Monday\cr
\_TIME&23:59\cr}}
$$

The built-in functions are summarized alphabetically in Appendix~L.
^^)built-in!macros) ^^)macro!built-in)

\dsection OVERLOADING OPERATORS and IDENTIFIERS.[8.2]

For special effects in the woven output, there are special commands to help
one change the appearance of operators and identifiers.

\dsubsection OVERLOADING OPERATORS. ^^(operators!overloading(

\parinserto{2}{5}{0.45}
One can change the printed appearance of an operator with the `{\ssbf @v}'
command. 

A feature common to both~\Cpp\ and \Fortran--90 is \It{operator overloading},
the ability to extend or redefine the definition of an operator such as
`\.{.FALSE.}'
or~'\.='.  \Fortran--90 even allows one to define new ``dot''
operators---for example, one might define the operator ``\.{.IN.}'' to test
for inclusion in a set.  In a nontrivial extension of the original design,
\FWEAVE\ allows one to define how overloaded
operators should appear on output---for example, it is much more readable
to read ``$\&{if}\.(x \in \\{set}\.)$'' than ``\&{if}\.(x\ \.{.IN.}\
\\{set}\.)''.  Indeed, this feature can be used even when the language
does not permit overloading in order to customize the appearance of the
woven output.

The \atcmd{v}~control code is used to change the appearance of an operator.
^^{operator!changing appearance of}
The format is

{\codemode
@v \It{new}_\It{operator}_\It{symbol}_\It{or}_\It{name} "\It{\TeX\ material}" \It{old}_\It{operator}
}
\noindent This means ``Display the new operator according to the \It{\TeX\
material}, but treat it like the old operator---e.g., unary or binary---for
formatting purposes.  The 
quoted \TeX\ material is treated just like a C~string, so for example if
you want to include a backslash you must escape it with another backslash.
For example, we can make an equals sign display on output as
a large left arrow by saying

{\codemode
@v = "\\\\Leftarrow" =
}
\noindent Then, if you say ``\.{x = y;}'', it will display as ``$x
\Leftarrow y;$''.  Two \Fortran\ examples are

{\codemode
@v .FALSE. "\.{.FALSE.}" .FALSE.
@v .IN. "\\in" +
}
\noindent which makes the operator \.{.FALSE.} display as ``\.{.FALSE.}''
instead of the default~${\cal F}$ (but still behave in the default
way---i.e., like an ordinary expression), 
and makes the operator~\.{.IN.} display as~``$\in$'' (and behave like a
binary operator).

This feature can go a long way toward enhancing readability of the woven
output, particularly when operators are actually being overloaded.  It can
also lead to arbitrarily bizarre output that no-one else will understand.
As usual, restraint is advised.

Examples of operator overloading can be found in the sample~\Cpp\ and
\Fortran--90 code in Appendix~E.
^^)operators!overloading)

\vfill\eject

\dsubsection OVERLOADING IDENTIFIERS. ^^(identifiers!overloading(

\parinserto{1}{5}{0.45}
One can change the printed appearance of an identifier with the `{\ssbf @W}'
command. 

Although operator overloading is quite useful, it does not allow one to
change the appearance of identifiers.  In its most general form, such a
facility becomes quite complicated; one must endow \FWEAVE\ with a
macro-processing facility analogous to that of \FTANGLE.  This has not been
done yet (probably it will be someday).  In the meantime, one has the
command~`\.{@W}, ^^:\>{@W}:
which provides a restricted form of such a facility.  \It{This command, new
with version~1.30, is
experimental, and not firmly established.  Changes in usage and/or syntax
may be made in future versions.}

The most general form of the `\.{@W}~command is

{\codemode
@W \It{identifier} "\It{replacement text}"
}
\noindent This means:  Replace any references to \It{identifier} in the
woven output with the \It{replacement text}.  

A more restrictive form is

{\codemode
@W \It{identifier} \\newmacro
}
\noindent which replaces references to \It{identifier} with a call to
\.{\\newmacro}.  (Note that there are no quotes in this form.)

The shortest form is

{\codemode
@W \It{identifier} .
}
\noindent which replaces references to \It{identifier} with a call to
\.{\\identifier}.  For example, the identifier~\\{x} normally appears in
woven output as ``\.{\\Wshort\{x\}}''.  If one says

{\codemode
@W x .
}
\noindent one will instead get the macro reference~``\.{\\x}'', which could
be defined to give a variety of special effects.

It should now be clear how the previous ``\&{call} \\{integrate}'' example
was formatted.  One simply said

{\codemode
@n
@
@W alpha .
@W beta .
@W fM "f_{\\\\rm M}"
@a
\Tab call integrate(x,alpha,beta,fM)
}

One of the important uses of this facility is to expedite special
formatting of array references.  This subject is discussed separately below
in the section on ``Special array formatting,'' where an example is given.
^^)identifiers!overloading)

\section RATFOR.[9.3] ^^(Ratfor:\RATFOR(

Closely related to macro preprocessing is the notion of \It{statement
translation}. ^^:statement!translation:
In statement translation, \FWEB\ recognizes a special keyword
or construction that is not part of the source language, and automatically
translates that construction into valid compilable code. It is a more
general operation than macro expansion, although it reduces to that in the
simplest cases.

\parinsert{2}{6}{0.6}
``Ratfor provides modern control flow statements..., so [one] can do
structured programming properly.''

In the present version of \FWEB, statement translation is active only when
the language is \Ratfor.  The \Ratfor\ language was introduced by \KP\ in
{\sl Software Tools} as a tool for explaining good programming practice; it
is also a vastly superior way of writing understandable \Fortran\ code. In
their words, ``bare Fortran is a poor language indeed for programming or
for describing programs. So we have written all of our programs in a simple
extension of Fortran called `Ratfor' (short for Rational Fortran). \Ratfor\
provides modern control flow statements\dots, so we can do structured
programming properly. It is easy to read, write, and understand, and
readily translates into Fortran\dots\ or similar high-level languages.''
Unfortunately, extant \Ratfor\ processors essentially convert the new
statements into pre-\Fortran--77 code, with many
\&{goto}'s, so the resulting code can be somewhat messy and hard to read.
If your code worked perfectly the first time, this would not be
an issue since you would never have to see the \Fortran\ file. However, if
it is necessary to work with a debugger (and it very frequently is!), then
it is the generated \Fortran\ code at which one will be looking. It is
desirable to make that code as readable (and as efficient) as possible.

Thus, \FTANGLE\ has been taught the \Ratfor\ language and, by default, will
translate it directly to \Fortran\ code.  Translations into both
\Fortran--77 and \Fortran--90 are supported.

(Certain existing codes use a now-archaic mode of \FTANGLE\ in which
\Ratfor\ code was just \TANGLE d into a \.{RAT} file that was intended to
be passed through a separate \Ratfor\ processor. \It{This mode has died; it
should not be used for new codes.} To tell \FTANGLE\ to \It{not} translate
\Ratfor\ statements, you must use the command-line option `\.{-q}'.)
^^:\>{-q}:

^^[Ratfor:\RATFOR!syntax] ^^[syntax!Ratfor:\RATFOR]
The syntax of the \Ratfor\ language understood by \FWEB\ is as C-like as
possible.  It features the following:

{\narrower
\Item The syntax is totally free-form.

\Item ^^{Ratfor:\RATFOR!declarations} ^^{Ratfor:\RATFOR!statements}
Declarations and statements are ended by ^{semicolons}. (An auto-semi
mode can fill these in for you; see below.)  

\Item ^^{Ratfor:\RATFOR!program units}
Program units should be begun by either the \&{program}, \&{subroutine},
\&{function}, or \&{blockdata} statement. Use \&{program main} instead of an
unnamed main program; the latter may confuse \FWEAVE.

\Item The body of the subroutine is
delimited by ^{braces} (as are groups of statements that form the bodies of
keywords such as \&{else} or~\&{do}).

\Item ^^{Ratfor:\RATFOR!declaring functions in}
^^[declarations!argument, in \RATFOR]
Functions are declared in the same way as the ``old'' style of
argument declaration in~C. (There is no concept of function prototyping.)
Thus, the outline of a \Ratfor\ function is

{\codemode
function f(x,y)
\Tab real x,y;
\{\}
}

\item{} (Actually, as far as the \Fortran\ code that is generated is
concerned, it makes no difference whether the function arguments are
declared before or after the opening brace.  However, it is useful
logically and typographically to set them off as suggested.)

\Item ^^{statement!\<{end}} ^^{Ratfor:\RATFOR!\<{end} statement}
No \&{end} statement should be used; that is filled in automatically when
\FTANGLE\ processes the closing brace. 

\Item ^^{statement!\<{return}} ^^{Ratfor:\RATFOR!\<{return} statement}
Function values can be returned with a \&{return} statement of the form
`\.{return \expr;}'. 

\Item ^^{Ratfor:\RATFOR!statement labels}
Numeric statement labels, if used, should be followed by a colon.

\Item ^^{Ratfor:\RATFOR!comments}
Comments should be C-style: \hbox{`\.{/*\dots */}'} or \hbox{`\.{//\dots}'}. 
^^:comment!Ratfor\actual\RATFOR: 

\Item When one is inside a recognizable \&{program}, \&{subroutine}, 
\&{function}, or \&{blockdata} unit, the built-in function \\{\_ROUTINE}
^^{\>{\UL ROUTINE}} 
expands to the name of the program unit.  (This is true only for \Ratfor;
\FTANGLE\ is not so intelligent in the other languages.)

\Item ^^{\>{++}} ^^{\>{--}} ^^{\>{+=}} ^^{\>{-=}} ^^{\>{*=}} ^^{\>{/=}}
^^{operator!post-increment} ^^{operator!compound assignment}
The special operators~`\.{++}', `\.{--}', `\.{+=}',`\.{-=}', `\.{*=}',
and~`\.{/=}' are allowed in restricted places; see the discussion in the
section ``Additional features.''  

\Item ^^{Ratfor:\RATFOR!character strings}
\Ratfor\ character strings must be
enclosed in double, not single, quotes (consistent with~C, but unlike
\Fortran--77).
^^{character!strings}
As in~C, single characters enclosed
by single quotes are interpreted as character constants ^^{character!constants}
and are translated
into the ASCII integer equivalent; ^^{ASCII!integer equivalent of}
for example, $\.{'a'} \to \.{97}$.

}

Thus, an example of a \Ratfor\ function
is as follows:

{\codemode
@r/
@m ERROR call error(_ROUTINE)
@a
real function f(x)
\Tab real x; // We should have $x \\ge 0$.
\{
real y;
\Par
if(x >= 0) y = sqrt(x);
else
\Tab \{
\Tab ERROR;
\Tab y = 0.0;
\Tab \}
\Par
return y;
\}
}

\Ratfor\ statements can be easily ``stacked''.
For example, the following is valid \Ratfor:

\vbox{

{\codemode
if(do_it)
\Tab for(i=1; i<100; i *= 2)
\Tab\Tab while(k < i)
\Tab\Tab\Tab do j=0,k;
\Tab\Tab\Tab\Tab a(i,j,k) = 1.0;
}
}
\noindent Note the simplicity of the construction: no \&{end} statements
are required to terminate the loops.

An important notion in the C~language whose essence is retained in
\Ratfor\ is the \It{compound statement}. ^^:statement!compound:
Here, a compound statement is any group of
statements delimited by braces. Compound statements may be used wherever a
simple statement may be. Thus, in the above example any or all of the last
four lines could be replaced by a compound statement---for example,

{\codemode
if(do_it)
\Tab \{
\Tab x = dx;
\Tab for(...)
\Tab\Tab while(...)
\Tab\Tab\Tab do ...
\Tab\Tab\Tab\Tab \{
\Tab\Tab\Tab\Tab a...;
\Tab\Tab\Tab\Tab b...;
\Tab\Tab\Tab\Tab \}
\Tab x *= alpha;
\Tab \} // |do_it|
}
\noindent Here, as in~C, the use of braces creates a quite concise and
readable code. 

^^[braces]
\parinsert{2}{7}{0.6}
``It is
truly remarkable how much heated debate can result from such trivial
questions as whether braces are better than {\ssbf begin} and {\ssbf
end}...'' 

[Some people disagree. Indeed, again quoting \KP, ``It is
truly remarkable how much heated debate can result from such trivial
questions as whether braces are better than \&{begin} and \&{end}\dots''
In this regard, it is very important to observe that in many situations neither
braces nor keywords are required to terminate loops; loops whose bodies are
simple statements terminate automatically, just as in~C.
The principle argument that appears to be raised against braces is that if
they enclose long blocks of code they can get lost or misplaced. However,
note that at the user's discretion braces can be labelled (the previous
example shows one possible style); furthermore,
such long blocks are strongly discouraged by the philosophy and design of
\WEB. As you know by now, the proper use of named modules leads to a
programming style in which no modules need be longer than, ideally, about a
dozen lines. For modules that short, it's very difficult to lose braces;
rather, the braces tend to enhance the logical structure and we believe
that they are more pleasing to, and more readily captured by, the eye than
verbose keywords. In any event, our design goal of syntactical consistency
with~C is obviously better achieved by using braces rather than keywords.
Therefore, within the framework of the present philosophy, keywords such as
\&{end do} or \&{end while} seem to represent a definite step backwords and
are not used.]

\subsection Ratfor--77 commands.[9.1.7]
^^(keywords!Ratfor:\RATFOR(

Here are the \Ratfor\ constructions recognized and expanded by \TANGLE. In
the following, the construction \.{\stmt} stands 
for either an arbitrary number of statements enclosed by braces (a compound
statement), or a simple statement terminated by a semicolon. (Recall that the
\Ratfor\ syntax is free-form, so the newlines and spacings in the examples are
inserted entirely for readability.)

\subsubsection {\bf if}.

The \&{if} statement looks exactly like that of~C (the \&{else} clauses are
optional): 
^^:\<{if}: ^^:\<{else}: ^^:\<{else if}:

{\codemode
if(\cond)
\Stmt
else if(\It{another condition})
\Stmt
else
\Stmt
}

\noindent There may be multiple \.{else if}'s.
Functionally, this statement is identical to
\Fortran's \&{if}\dots\&{then}\dots\&{else
if} \dots\&{then}\dots\&{else}\dots\&{end if}
construction (into which it is expanded), but the keywords have been
abolished. The simple 
\Fortran\ \&{if}, such as `\.{if(x < 0.0) x = 0.0;}',
is a special case of the general construction. For simplicity, \Ratfor\
also expands this into an `\&{if}...\&{then}...\&{endif}'.

\subsubsection {\bf while}.

The \&{while} statement is also equivalent to that of~C:
^^:\<{while}:

{\codemode
while(\cond)
\Stmt
}
\noindent The condition is checked. If it is true, the body of the \&{while}
is executed. Then the process repeats.  If the condition is false, control
passes to the first statement after the body of the \&{while}. This means
that if the condition is false initially, the loop is not executed even
once.

\subsubsection {\bf for}.

The \&{for} statement is equivalent to that of~C. It is a souped-up version
of the \&{while} that includes initialization and reinitialization:
^^:\<{for}:

{\codemode 
for(\It{initialization}; \It{condition}; \It{reinitialization}) 
\Stmt
}

\noindent The
initialization (which must be a \It{single} \Fortran\ statement;
C~programmers beware!)
is performed. The condition is tested. If it is false,
processing terminates. If is is true, then the body of the \&{for} is
executed. At the bottom of the loop, the reinitialization (which must also
be a \It{single} \Fortran\ statement) is performed;
then the condition is tested again and the processing iterates. For example,

{\codemode
for(i=0; i<10; i++) a(i) = i;
}

\noindent is equivalent to \Fortran--90's 

{\codemode
do i=0,9
\Tab a(i) = i
end do
}
\noindent However, it is important to note that for arbitrary bodies even
this simple \&{for} is \It{not} equivalent to the \Fortran~\&{do}, since
\Fortran\ does not allow one to tamper with the loop index within the loop
but there is no such restriction in \Ratfor\ or~C. Therefore, the
construction is translated into an \&{if} and a \&{goto}; no attempt is
made to optimize it into a \&{do}.  \Ratfor\ programmers working with
vectorizing compilers should employ \&{do}'s instead of simple \&{for}'s
for critical loops.

\subsubsection {\bf repeat---until}.

The \&{repeat}--\&{until} construction executes the body before the
condition is tested, so it is guaranteed to be executed at least once; it
corresponds to the \&{do}--\&{while} construction of~C: 
^^:\<{repeat}:^^:\<{until}:

{\codemode
repeat
\Stmt
until(\cond);
}
\noindent Unlike the corresponding loop in~C,
the \&{until} clause is optional. If it is omitted, one gets an
infinite loop that must be broken out of by a \&{break} or \&{goto}.
That loop is equivalent to C's \.{while(1) \{...\}} or \Fortran--90's \.{do
\{...\}}. 

\subsubsection {\bf do}.

The \Ratfor~\&{do} statement is fundamentally \Fortran's:
^^:\<{do}:

{\codemode
do \It{index}=\It{lower},\It{upper}[,\It{increment}]
\Stmt
}
\noindent or

{\codemode
do \It{index}=\It{lower},\It{upper}[,\It{increment}];
\Tab\It{simple statement};
}
\noindent Functionally, these are equivalent to

{\codemode
for(index=lower; index<=upper; index += increment)
\Stmt
}

\noindent but the \&{do} may be implemented more efficiently by the compiler.
Note the semicolon after \It{increment} in the second example. This is
annoying, as it looks 
different than the syntax for the \&{for} statement.  Unfortunately, the
standard \Fortran\ syntax is simply incompatible here with the uniform
\Ratfor\ syntax. (If a simple statement follows the
\&{do}, some terminator is required in order to separate the increment from
the beginning of the statement. The carriage return at the end of the
physical line cannot be used because the syntax is free-form.)  If you
would like to make things look more symmetric, you could define a \WEB\
macro:

{\codemode
@m DO(i,min,imax) do i=imin,imax;
}
or, more simply and also more generally,

{\codemode
@m DO(i,...) do i=#.;
}
\noindent [If you are using the auto-semi mode ^^{mode!auto-semi}
(see below), you should omit the semicolon; it will be inserted for you.]
Note that the \Ratfor\ syntax makes multiple \&{do} loops look very clean;
neither braces nor \&{end} keywords are required in the following example:

{\codemode
do i=1,10;
do j=1,10;
\Tab a(i,j) = 0.0;
}

\subsubsection {\bf break}, {\bf next}.

In the bodies of the above loops (\&{if}~statements are not loops), the special
commands \&{break} and \&{next} are allowed.  The \&{break} command
^^:\<{break}: 
exits the loop immediately. The
\&{next} command ^^:\<{next}:
is functionally equivalent
to the \&{continue} statement of~C. Following \KP, ``\&{next} goes to the
\It{condition} part of a \&{while}, \&{do}, or \&{until}, to the top of an
infinite \&{repeat} loop, and to the \It{reinitialize} part of a \&{for}.''
(Note that other statement processors may implement this statement
differently.) 

Only one level of looping can be broken
out of by \&{break}. This restriction is deliberate, not fundamental. A
\.{break\ $n$} statement, though very feasible to code, is not
allowed partly because C~does not and partly (equivalently?) because it is
felt that its 
presence would make certain coding errors more likely. To conveniently
break out of several levels of looping, use \&{goto}; this is one of its
few legitimate uses\cite{Knuth}.

\subsubsection {\bf switch}.

Finally, we have the \&{switch} statement, again functionally equivalent
to that of~C: 
^^:\<{switch}: ^^:\<{case}: ^^:\<{default}:

{\codemode
switch(\expr)
\Tab \{
\Tab case \It{integer\_expression}:
\Tab\Tab .
\Tab\Tab .
\Tab\Tab break; // Use this to prevent falling through to the next case.
\Tab .
// More case statements.
\Tab .
\Tab default:
\Tab\Tab .
\Tab\Tab .
\Tab\Tab break; // Optional here, but still a good idea.
\Tab \}
}
\noindent The \.{\expr} is evaluated at run time and converted to an
integer. If any of the listed cases correspond to that integer, control is
passed there. Otherwise, if the optional \&{default} statement is present,
control is passed there. (It is not necessary that the \&{default} be last
in the \&{switch}.) Otherwise, the entire \&{switch} body is skipped.

\parinsert{2}{4}{0.35}
Use {\ssbf break} to terminate a {\ssbf case}.

The arguments of the cases should be or expand to single integers. Lists of
cases, as in `\.{case 2-5:}', are not allowed. ^^{cases, list of}
If the cases are all pure
numbers or macros known at \TANGLE\ time, then in certain circumstances the
\Ratfor--77 \&{switch} will be implemented using a computed \&{goto}. This
will occur 
if the list of cases is sufficiently dense, with few gaps, or if the number
of cases is sufficiently large, provided the spread in the case values is
not too great.  Otherwise, in \Ratfor--77 the
\&{switch} is expanded into a series of \&{if} statements. In this case,
if the
\&{switch} is lengthy, it will pay to put the most frequently expected case
first.  In \Ratfor--90 the \&{switch} is translated into a ``\&{select case}''
construction. 

More precisely, the decision of whether to use a computed \&{goto} is based
on three parameters---$r$, $m$, and~$s$. Let the number of cases in the
\&{switch} be~$n$ and the spread of case values, plus~1, be~$\Dv$. The
computed \&{goto} is chosen if both $n > m$ and $\Dv < s$ or, failing that, if
$\Dv/n \le r$. By default, $m = 5$, $s = 128$, and $r = 2.0$.  If you
absolutely don't want the computed \&{goto} for some reason (maybe because
it doesn't vectorize), use $r = 0.0$.  These
parameters can be set by the user through the command-line option
``\.{-rg}''.  ^^{\>{-rg}}
The format is, for example, ``\.{-rgm5s128r2.0}''. The \.m, \.s,
and~\.r keyletters may appear in any order, or may be absent. \It{(Now that the
style file exists, these parameters should really be defined there. That
will be done at some point.)}
        
In the \&{switch}, the \&{break} statements are optional. If they are
missing, control just continues to the next case. This is in accord with
C's behavior, but {\it is in disagreement with the original \Ratfor\ design}.

Note that a \&{next} statement appearing inside a \&{switch} has nothing to
do with that \&{switch}.  (The \&{switch} is not a loop.)  Rather, it is
related to whatever loop encloses the \&{switch}.

Here is an example of a \&{switch}. ^^<\<{switch}>
It assumes that the single
character~$c$ has been read. It should be either `\.y' or~`\.n', in either
upper or lower case. If it is~`\.y', the \\{execute} subroutine is called;
if it is~`\.n', 
nothing is done; if it is anything else, an error routine is called.
Note how the lower-case cases fall through to the upper-case ones, and how
the \&{break} statement is used to terminate the processing of a group of
cases. 

{\codemode
switch(ichar(c)) // Use intrinsic function to return integer value.
\Tab \{
\Tab case 'y':
\Tab case 'Y':
\Tab\Tab call execute;
\Tab\Tab break;
\Par
\Tab case 'n':
\Tab case 'N':
\Tab\Tab break;
\Par
\Tab default:
\Tab\Tab call error(c);
\Tab\Tab break;
\Tab \}
}

\dsubsection Ratfor--90 commands.[9.2.5]

In \Ratfor--90, additional constructions are supported.  In general, where
\Fortran--90 has a compound construction that ends with an \&{end}
statement, such as \&{type person}\dots\&{end type person}, \Ratfor\
abolishes the \&{end} statement and encloses the statements with braces.
It will expand the construction into valid \Fortran--90, including the
optional labelled form of the \&{end} statement, such as \&{end module}.
Furthermore, \Fortran--90 allows optional symbolic labels on such compound
constructions.  \Ratfor--90 permits these as well, as in

{\codemode
test: if(x)
\Stmt
}
\noindent This construction will be expanded into code that ends with
``\&{end if test}''.  Such symbolic labels should \It{not} be declared with
the automatic statement numbering facility;  that is, do \It{not} say
`\atcmd{m test \#:0}'.

\subsubsection {\bf module}. ^^:\<{module}:

The \&{module} statement is analogous to the \&{class} statement of \Cpp:

{\codemode
module \It{module\_name}
\Stmt
}
\noindent As an example,

{\codemode
module work_arrays
\Tab \{
\Tab integer n;
\Tab real, allocatable, save :: A(:), B(:,:), C(:,:,:);
\Tab \}
}

\subsubsection {\bf type}. ^^:\<{type}:

The \&{type} statement is analogous to the \&{struct} statement of~C:

{\codemode
type \It{type\_name}
\Stmt;
}
\noindent As an example,

{\codemode
type line
\Tab \{
\Tab real, dimension(2,2) :: coord;   // $x_1$, $y_1$, $x_2$, $y_2$.
\Tab real                 :: width;   // Line width in centimeters.
\Tab integer              :: pattern; // 1 for solid, 2 for dash, 3 for dot.
\Tab \};
}
\noindent Note the terminating semicolon, which is consistent with the
\&{struct} statement of~C and~\Cpp.

\subsubsection {\bf interface}. ^^:\<{interface}:

The \&{interface} statement is \Fortran--90's way of overloading operators
or procedures.  The corresponding \Ratfor\ statement has one of the three
following forms: 

{\codemode
interface \It{procedure\_name}
\Stmt
\Par
interface operator(\It{operator})
\Stmt
\Par
interface assignment(\It{assignment operator})
\Stmt
}
\noindent As an example,

{\codemode
interface operator(*)
\Tab \{
\Tab function boolean_and(b1,b2)
\Tab\Tab \{
\Tab\Tab logical :: boolean_and(size(b1));
\Tab\Tab logical, intent(in) :: b1(:), b2(size(b1));
\Tab\Tab \}
\Tab \}
}

\subsubsection {\bf where}. ^^:\<{where}:

The \&{where} statement is supported (the \&{else} clause
is optional):
^^:\<{where}: ^^:\<{else}:

{\codemode
where(\cond)
\Stmt
else
\Stmt
}

\subsubsection {\bf contains}, {\bf private}, {\bf sequence}.
^^:\<{contains}: ^^:\<{private}: ^^:\<{sequence}:

The keywords \&{contains}, \&{private}, and \&{sequence} should be followed
by colons; for example,

{\codemode
subroutine outer
\Tab\{
\Tab ...
   contains:
\Tab subroutine inner(b)
\Tab\Tab\{...\}
\Tab\}
}
^^)keywords!Ratfor:\RATFOR)

\dsubsection Additional features of \Ratfor.[9.3.4]

A few additional topics are useful to discuss.

\dsubsubsection \Ratfor's automatic comments.
^^:comment!Ratfor\actual\RATFOR!automatic: 

As \FWEB\ translates \Ratfor\ statements, it typically writes comment lines
to the output file to help one correlate the source statement with the
translated output. (Look at some sample output for examples.)  If one
wishes to suppress such comments, he may use the command-line option
`\.{-k}'. ^^{\>{-k}}
See the detailed description under `Command-line options'.

\comment
We end the discussion of the \Ratfor\ commands with a simple example that
illustrates the basic \Ratfor\ syntax. (It does not illustrate most of the
commands; 
many
more complicated examples can be found in \KP.)  The goal is to sum the first
$n$~integers. This is done in a \Ratfor\ function called from a \Ratfor\
main program. The answer is printed out by a C~function, because I/O is so
much nicer in~C and furthermore the exercise can then illustrate the
ubiquitous considerations about passing arguments between mixed languages;
recall that \Fortran\ passes addresses while C~passes values.

{\codemode
@r
@ Sum the first n integers.
@m SEE(n) see(n,sum(n))
@a
program main
\{
integer k;
\Par
do k=1,10;
\Tab SEE(k);
\}
\Par
@c
@<C@>@;
\Par
@ A Ratfor function that returns the sum of the first n integers.
@a
integer function sum(n)
\Tab integer n;
\{
integer k,s;
\Par
s = 0;
for(k=1; k<=n; k++) s += k;
\Par
return s;
\}
\Par
@ We'll do the I/O in C.
@<C@>=
see(pn,ps)
\Tab int *pn,*ps;
\{
printf("sum(%d) = %d\\n",*pn,*ps);
\}
}
\endcomment

\dsubsubsection Automatic insertion material. ^^[automatic insertion]
^^[declarations!automatic insertions after]
^^[insertion!automatic] 

It is often desirable to include common material at
the beginning of each program unit, such as the phrase ``\.{implicit
none}''.  
Since \Ratfor\ is aware when a program unit begins, it is
feasible to automate such insertions.  The material to be inserted is
indicated by a special notation that extends the syntax of a \WEB\ macro
definition, as follows:

{\codemode
@m[\It{ctrl-list}] \It{macroname} \It{macro text}
}
\noindent Here the characters in the \It{ctrl-list} between the square
brackets signify for which 
kind of program unit the material is to be inserted; they
may be one or more of the following:
$$\vbox{\halign{\hfil\tt#&\ ---\ #\hfil\cr
b & \&{block data}\cr
f & \&{function}\cr
i & \&{interface}\cr
m & \&{module}\cr
p & \&{program}\cr
s & \&{subroutine}\cr
* & All of the above.\cr
}}$$
Thus, if you say

{\codemode
@m[pfs] AUTO implicit none
}
\noindent the text ``\.{implicit none} will be inserted on the lines
immediately following every \&{program}, \&{function}, and \&{subroutine}
declaration.  (There is at present no way to prevent this insertion for a
particular program unit; it is either all or none.)

At present, 
you cannot stack automatic material for a particular program unit.  Thus,
after the statements

{\codemode
@m[pfs] AUTO1 implicit none
@m[f] AUTO2 implicit integer[i-n]
}
\noindent functions will begin with the text ``\.{implicit integer[i-n]}''
while the main program and subroutines will begin with ``\.{implicit
none}.''  (In the future, such stacking may be allowed.)

Note that there is nothing special about the macro names used in these
extended definitions.  Thus, in the above example one could have replaced
\\{AUTO1} by~\\{X} and \\{AUTO2} by~\\{Y} and achieved precisely the same
effect.  

\dsubsubsection Semicolons.

We now return to the issue of semicolons. ^^[semicolons]
\It{It is highly recommended that the complete free-form
syntax, ^^{syntax!free-form}
with semicolons as statement terminators, be used for all new code.}
However, it is recognized that an intermediate step may expedite conversion
of existing \Fortran\ codes. One can initiate an \It{auto-semi} mode with
the command-line option `\.{-;}'. In this mode, the expected \Ratfor\ syntax
is midway between \Fortran's and~C's.

The auto-semi mode ^^:mode!auto-semi:
is almost free-form syntax, except that carriage returns
end statements when the line is not ``obviously continued''. By definition,
a statement is obviously continued ^^:statement!obviously continued:
if it ends with any of the following
characters between double quotes: ``\.{+-*=\{\}\^\&|(:><,}''. In this case,
\WEB\ just goes on to the next line and continues to read. Otherwise, the
input driver terminates the statement with a semicolon, then ships it off
to the innards of \WEB. (This clarifies why the character '\.\}' is part of
the previous list: ``Obviously continued'' really means ``don't end this
line with a semicolon.'')  Continuation can be forced by ending a line with
a backslash; the backslash is discarded. (For compatibility with previous
\Ratfor\ implementations, a trailing underscore will also continue a line
except when it is part of an identifier; however, its use is definitely not
recommended.) One implication of these rules is that in the auto-semi mode
no semicolon should end the first line of a \&{do}; say

{\codemode
do i=1,n
\Tab a(i) = i
}

\noindent (Neither statement is obviously continued; the input driver will
supply semicolons for both.)

\[According to these rules, lines such as `\.{for(...)}' will be terminated
by a semicolon. In free-form syntax, such a semicolon would be incorrectly
interpreted as
a null statement. In the auto-semi mode, however, a special check is made
for such a supplied semicolon, which is discarded if present. Thus, the
\Ratfor\ syntax behaves consistently in both syntax modes.\]

In the auto-semi mode, an additional commenting style is allowed: anything
between `\.{\#}' and the end of the line denotes a comment. 
^^{comment!Ratfor:\RATFOR}
This is changed
by the input driver into a standard C-style comment. However, it is
recommended that this \Ratfor\ commenting style be avoided; \It{it will
probably be allowed to die with the next major release}.

\ddsubsubsection \FWEB\ {\it sans} Ratfor. ^^[Ratfor:\RATFOR!deleting]

\Ratfor\ is a self-contained subset of \FWEB.  It is possible to create
\FWEB\ processors that do not contain most of the code associated with
\Ratfor\ and are therefore smaller.  This may be relevant for users of
personal computers.  See the installation notes in
\.{INSTALL\_FWEB.tex} for more information. ^^{\>{INSTALL\UL FWEB.tex}}

Once again, it is recommended that if you are a \Fortran\ programmer you
seriously consider \Ratfor.  It will make your life simpler and your
documentation superior.

The \Ratfor\ commands are summarized in Appendix~L.
^^)Ratfor:\RATFOR)

\section ADDITIONAL LANGUAGES.[10.2]

In addition to the principal supported languages of~C, \Cpp, \Fortran, and
\Ratfor, several other languages are supported at various levels of
experimental development:

\subsection TEX mode. ^^(TEX mode(

\parinserto{2}{5}{0.4}
``\FWEB\ offers restricted support for tangling and weaving \TeX\ code.''

As an experiment,  \FWEB\ offers restricted support for tangling and
weaving \TeX\ code.  This provides a superior way of maintaining and
documenting \TeX\ input files, for example macro packages such as
\.{fwebmac}. ^^{\>{fwebmac}}  
 One selects the \.{\TeX} language with the command~\atcmd{Lx}.  \FTANGLE\
will write its \TeX-language output into a file 
with the extension~\.{.sty}; that can be overridden by the style-file
option ``\.{suffix.TEX}''.
\FWEAVE\ will, as usual, create a file with the
extension \.{.tex}.  As an example, \.{fwebmac} itself is now maintained
with \FWEB. \FTANGLE\ has been used to create the ``executable'' (i.e.,
\TeX-compatible) file \.{fwebmac.sty} ^^{\>{fwebmac}!\>{.sty}}
from the master file \.{fwebmac.web}. ^^{\>{fwebmac}!\>{.web}}
This explains why \FWEAVE's \.{tex}
output files begin with the command ``\.{\\input fwebmac.sty}'' instead of just
``\.{\\input fwebmac}''.  The latter would incorrectly read in \.{fwebmac.tex},
^^{\>{fwebmac}!\>{.tex}}
which is \FWEAVE's output intended for typesetting.

In \TeX\ mode, \TeX-like comments (begun with~'\.\%', or more precisely
begun with any character whose category code is~14) are displayed in the
standard C-style format, except that if the last character on the line
is~'\.\%' it is displayed as is. If several adjacent lines consist solely of
\TeX-like comments, they are concatenated into one long comment.

Actual spaces in the source are displayed as~'\.\ ', with two exceptions.
First, tabs in the source are turned into invisible spaces.  Second, spaces
after multi-character control sequences are also printed as invisible spaces.
If this is not done, the output tends to become
extremely dense with the '\.\ '~symbol.

Note that a full-featured implementation of
\WEB\ processing for \TeX\  is quite difficult because \TeX\ can, for
example, change 
category codes on the fly from within very complicated macro constructions.
A truly general \WEB\ for \TeX\ should probably be completely integrated
into \TeX\ itself.  This daunting possibility is far beyond the scope of the
present \FWEB\ project.  However, it is possible to give \FWEB\ some help
and thus deal with a variety of circumstances.  In particular, one can force
\FWEB\ to change the category code of a character.  When \FWEB\ starts up,
it has assigned default category codes to each ASCII character---for
^^{ASCII!category codes for}
example, the default category code of~'\.\\' is~0; that of~'\.A' is~11;
that of~'\.\%' is~14.  To change the category code, say in the definition
section

{\codemode
@f `\It{\TeX char} \It{new}_\It{cat}_\It{code}
}
\noindent where here, as when changing category codes in \TeX, \It{\TeX
char} has one of the forms~`$c$', `\.\\$c$', or~`\.{\^\^$c$}', $c$~being a
visible ASCII character. For example, the command

{\codemode
@f `! 14
}
\noindent will make the exclamation point also function as a comment
character.

At this early stage of development, the \It{only} thing that is guaranteed
is that \.{fwebmac.sty} will be created correctly from \.{fwebmac.web}.
Feel free to experiment with \FWEB's \TeX\ language, but don't expect
perfection yet.  However, suggestions are welcome.


A sample of woven output from the \TeX\ mode may be found in
\.{fwebmac.tex}, which is typeset in Appendix~F.
^^)TEX mode)

\subsection MAKE mode. ^^(MAKE mode(

Someday \FWEB\ may also understand the syntax of \Unix\ \.{make} files.
^^)MAKE mode)

\Knuth
\section CONTROL CODES.[11.100] ^^(control codes( ^^[commands!control codes]

We have seen several ^{magic} uses of~\atcmd{} signs in \.{WEB} files, and it
is time to make a systematic study of
these special features. A \.{WEB} {\sl control code\/}
^^:control codes:
is a two-character combination of which the first is `\.@'. \[(The only
exceptions are the three-character combinations~\atcmd{/*} and~\atcmd{//}.)\]

Here is a complete list of the legal control codes. (Some of these codes
can be changed by the user, although this is not recommended; see the
section below on the style file.)  The 
abbreviations~$L$, $T$, $C$, $M$, $Co$, $S$, and/or~$H$ following each code
indicate 
whether or not that code is allowable in limbo~($L$), in \TeX\ text~($T$),
in \[code\] text~($C$), in module names~($M$), in comments~($Co$), 
in strings~($S$), and/or in change files~($H$).  A bar over such a letter
means that the control code 
terminates the present part of the \.{WEB} file; for example, 
$\overline L$~means that this control code ends the limbo material before
the first module.  (A shorter summary of the control codes is presented in
Appendix~L.) 

\gdef\@#1(#2)[#3] {\subsection\cc{@#1}\kern1em(#2).\par
%\yskip
%\hangindent 2em
%\noindent\.{@#1\unskip \spacefactor1000{ }}
\noindent
%\kern2em
$[#3]$\quad}

%\parindent0pt
%\everypar{\hangindent 2em\kern2em}

\gdef\cc#1{{\tt #1}}
\gdef\oP{\overline C}
\gdef\oT{\overline T}

\@@(the character '\cc{@}')[Co,L,M,C,S,T] ^^:\>{@@}: 
A double \.@ denotes the \hl{single character~`\.@'}. 
This is the only control code that is legal in comments and in strings.
\[For example, to get the output `\.{"Is there a missing @z?"}', one must
type in the 
\WEB\ source file `\.{"Is there a missing @@z?"}'. This is also one of the
few control 
codes that is legal in limbo (the only others being the language
commands~\atcmd{c}, \atcmd{r}, \atcmd{n}, and~\atcmd{L\It{l}}, and the
ignorable commentary commands~\atcmd{z} and~\atcmd{x}.)\]

\@|(literal vertical bar [\TeX\ text])[Co,T] ^^:\>{@"|}: ^^:vertical bar,
literal: 
In \TeX\ text, this affords a way of inserting the \hl{vertical bar}~`\.|'.
This is particularly useful within \LaTeX's \.{verbatim} environment.
^^{environment!verbatim}
For example, 

{\codemode
\\begin\{verbatim\}
Consider the expression @|x != y@|.
\\end\{verbatim\}
}
\noindent Without the~\.{@}s, \WEAVE\ would translate the bars and the
enclosed material into the \TeX\ macros appropriate for code mode.

In code text, this command is instead an optional line break in an
expression.  See the discussion below.

\@\SP(begin unstarred module)[\overline L,\oP,\oT] ^^:\>{@\ }: 
^^:module!beginning!unstarred:
This denotes the beginning of a \hl{new (unstarred) module}.
^^{module!unstarred}
A tab mark or end-of-line (carriage return)
is equivalent to a space when it follows an \.@ sign.

\comment
\parinsert{2}{3}{0.4}
``The very first module should be starred.''
\endcomment

\@*(begin a starred module)[\overline L,\oP,\oT] ^^:\>{@*}: 
^^:module!beginning!starred:
This denotes the beginning of a \hl{new starred module},
^^{module!starred} 
i.e., a module that begins a new major group. The title
of the new group should appear after the~\atcmd{*}, followed by a period.
\[This title will be entered in the table of contents.\] As explained
above, \TeX\ control sequences should be avoided in such titles unless they
are quite simple. When \.{WEAVE} and \.{TANGLE} read an~\atcmd{*}, they print
to the terminal an asterisk followed by the current module number, so that
the user can see some indication of progress. The very first module should
be starred.
\endKnuth

If the group title is immediately followed by a non-negative integer~$n$,
the title is considered to be of level~$n$, where $n = 0$ corresponds to a
major section, $n = 1$ corresponds to a primary subsection, and so on.  The
\.{fwebmac} macros can be defined to treat these levels in different
ways---for example, the appearance of a subsection entry in the table of
contents can be modified by appropriate macro definitions.

\Knuth
\@A(begin code part of unnamed module)[\oP,\oT] ^^:\={@a}{@A}: 
^^:module!part!code:
\hl{The \[code\] part of an unnamed module}  
^^{module!unnamed}
begins with~\atcmd{A} (or~\atcmd{a}; see below).
\It{(This is a change from the original \WEB, which
used~\atcmd{p} (for \PASCAL) and from \CWEB, which used~\atcmd{c}. In
designing \FWEB, it was felt most logical to reserve 
these commands for actually switching into a particular language; this is an
operation distinct from beginning the unnamed module.)}
This causes \.{TANGLE} to append the following  code
to the initial program text~$T_0$ as explained above. The \.{WEAVE}
processor does not cause an~\atcmd{A} to appear explicitly in the \TeX\
output, so if you are creating a \.{WEB} file based on a \TeX-printed
\.{WEB} documentation you have to remember to insert~\atcmd{A} in the
appropriate places of the unnamed modules.
\endKnuth

\@a(begin code part of unnamed module; mark first non-reserved word)%
[\oP,\oT] ^^:\>{@a}: Equivalent to~`\atcmd{A@[}'. That is, the first
non-reserved word following the~\atcmd{a} will be marked as defined in this
module.  This convention helps circumvent the forward-referencing problem;
see the discussion about ``Forward references'' below.

\@b(insert breakpoint command)[C] ^^:\>{@b}: ^^{commands!breakpoint}
^^{breakpoint command} 
When the ^{debugging} mode is turned on (which means when 
the \.{\_BP} macro has been defined from the command line; see discussion
below), the \atcmd{b}~command means \hl{insert a breakpoint command}.
When debugging is off, this command is ignored.

\@c(set language to~C)[L,C,T,H] ^^:\>{@c}: ^^:language!setting!C:
The \atcmd{c}~command means \hl{set the current language to~C}.
^^{language!C} 
\It{It does not mean begin the unnamed module, as
it did in Levy's \CWEB.} (See the detailed discussion of language
commands for more information.) 

\@c++(set language to~\Cpp)[L,C,T,H] ^^:\>{@c++}: ^^:language!setting!\Cpp:
The \atcmd{c++}~command means \hl{set the current language to~\Cpp}.
^^{language!\Cpp}

\@D(define outer macro)[\oP,\oT] ^^:\={@d}{@D}: \hl{Definitions of outer
macros} ^^:macro!outer!defining: 
begin with~\atcmd{D} (or~\atcmd{d}; see below), followed by
the code text for the macro syntax appropriate for the language currently
in force. These definitions must be made in the definition
part,  ^^{definition!part} 
which consists of any number of
macro definitions (beginning with~\atcmd{d} \[or~\atcmd{m}\]), format
definitions (beginning 
with~\atcmd{f}), \[preprocessor commands (beginning with~\atcmd{\#}), limbo
text 
definitions (beginning with~\atcmd{l}), operator overloading instructions
(beginning with~\atcmd{v}), identifier overloading instructions (beginning
with~\atcmd{W}), and language commands\], intermixed in any order.

For \Fortran, the syntax should be that for the
\.{m4} preprocessor; for~\C, it should be that of the C~preprocessor.
For \Ratfor, outer macros should never be used, since \TANGLE's
macro-processing capabilities are intended to provide a self-contained
means of getting directly from the \WEB\ source to compilable \Fortran.
Outer macros are simply copied to the beginning of the appropriate output
file. If the text of the macro contains an identifier that is a \WEB\
macro, \It{that macro will be expanded}.

The companion command~\atcmd{u} undefines an outer macro.

\@d(define outer macro; mark macro name defined)[\oP,\oT] ^^:\>{@d}:
Equivalent to `\atcmd{D@[}'.  See discussion about ``Forward references''
below. 

\Knuth
\comment
\parinsert{4}{3}{0.4}
``Module names can be formatted.''
\endcomment

\@f(format identifier)[\oP,\oT] ^^:\>{@f}: 
^^:definition!format: ^^:formatting!identifiers: ^^:formatting!module names:
\hl{Format definitions} begin with~\atcmd{f}; they cause 
\.{WEAVE} to treat identifiers or module names in a special way when they
appear in 
\[code\] text. The general form of a format definition is 
\atcmd{f} \|l \|r, followed by an optional comment, where \|l is an identifier \[or a 
module name\] and~\|r is an
identifier; \.{WEAVE} will subsequently treat~\|l as it
currently treats~\|r. \[The formatting is \It{language-specific}; it only
applies to identifiers used in the language  in force at the point the
format statement is encountered.\]
This feature allows a \.{WEB} programmer to invent
new reserved words and/or to unreserve some  reserved
identifiers. \[Note that module names can be formatted. 
^^{formatting!module names}
By default,
module names are interpreted as expressions. However, sometimes you use
them in other contexts, such as replacing a bunch of type specifications.
In this situation, you should say something like ``{\tt @f @<Common blocks@>
common}''.\] 
\endKnuth

An extension of the \atcmd{f}~command is used when the language is \.{TEX}
to change the category code of a character. The format is `\atcmd{f}
\.\`\It{\TeX char} \It{new\_cat\_code}'.  See the discussion of \TeX\ mode
for more details. 

\@i(include a file)[\It{web file}] ^^:\>{@i}: ^^:file!including:
\Levy: The web file itself can be a combination of several files.
When \WEAVE\ or \TANGLE\ are reading a file and encounter the control
code~\atcmd{i} at the beginning of a line, they interrupt their reading and
start reading the file named after the~\atcmd{i}, much as the
C~preprocessor does when it encounters an \&{\#include} line. After the
included file is done, they go back to the next line of the original file.
The file name following~\atcmd{i} can be surrounded by double quotes or
not; it should be made up of visible ASCII characters only, not including
double quotes.  Include files can nest, with level~0 being the primary
level associated with the source \WEB\ file.  Optionally, a second file
name also may be given.  Just as on the command line, this names the
^{change file} associated with the new include file.  This name is in
effect for all higher levels of nesting, but is forgotten when the include
file ends and control reverts to the next lower level.  If no change file
is specified at any level, the one in effect at the time of the include
continues to be used.  Automatic file-name completion is done when the
command-line option~`\.{-e}' is in effect; otherwise, you must give the
complete name of the file, including extensions such as `\.{.web}'.

\FWEAVE\ will print the name
of the current include file at the beginning of each section.  However,
note that there is no need that a file included by~\atcmd{i} consist of a
complete module.  Include files may be included anywhere, in either the
\TeX\ part, the definition part, and/or the code part; they may, in
principle, consist of arbitrary fragments of code.  Whenever possible,
however, it is best to stick to complete modules for included files.

By default, include files are searched for in the current directory.
However, if the environment variable \\{FWEB\_INCLUDES} is defined, then
its contents are interpreted as a colon-delimited list of paths to be
searched for the include file.  (The same format as \Unix' \\{PATH}
variable is used.)  In addition, whether or not that variable
is defined, one can append to the include path list by means of the
`\.{-I}'~command-line option. ^^{\={-i}{-I}}

\It{(The following is rendered obsolete by the previous paragraph; the
feature will probably be deleted in a future release.)}
File names in \atcmd{i}~commands may begin with a prefix followed by a colon,
as in ``\.{LN:file\_name}''. The intention is that \.{LN}~behaves like a
logical name under~VMS. In fact, under~VMS \.{LN}~is just left alone.
However, under \Unix\ \.{LN}~is assumed to be an environment variable and is
expanded. Thus, if one says ``\.{setenv LN /fweb}'' then
``\.{LN:file\_name}'' will expand to ``\.{/fweb/file\_name}'' (note that
the last slash was inserted automatically).  This mechanism is intended to
enhance portability of \WEB\ sources between various operating systems.

\@I(optionally include a file)[\It{web file}] ^^:\={@i}{@I}: This command is
like~\atcmd{i}, except that in 
special cases \FWEAVE\ will not process it completely.  The special cases
are when the command-line options~`\.{-i}' or~`\.{-i!}' are used. In
particular, when `\.{-i}'~is in effect, files included via~\atcmd{I} will be
processed but not printed in the woven output.  (This helps save trees.)
See the description of the command-line options below for more information
about this \It{experimental} feature. 

\@L(set language)[L,C,T,H] ^^:\={@l}{@L{\it l}}: ^^:language!setting:
The command~\atcmd{L$l$} sets the language to~$l$, where $l \in
\{\.c,\.n,\.r,\.x\}$.  Optional arguments to this command enable one to
invoke~\Cpp, \Fortran--90, or \Ratfor--90.  See the detailed discussion of
languages above.

\@l(specify limbo text)[\oP,\oT] ^^:\>{@l}: ^^:limbo!text:
This command specifies
\hl{limbo text}.  It must 
be followed by a double-quoted string, in which special characters are
escaped just as in~\C.  The contents of that string are
written out verbatim by \FWEAVE\ just before the limbo section is copied to
the output.  Thus, if there was just one limbo text command of the form

{\codemode
@l "\\\\def\\\\greeting\{Hello\}\\n\\\\def\\\\done\{Goodbye\}"
}
\noindent the output \.{tex}~file would begin with the lines

{\codemode
\\input fwebmac.sty
% --- Limbo text definitions from @l ---
\\def\\greeting\{Hello\}
\\def\\done\{Goodbye\}
}
\noindent Note the use of C-like escape sequences such as~`\.{\\\\}'
or~`\.{\\n}'. 

\@M(define a \WEB\ macro)[C,\oT] ^^:\={@m}{@M}: ^^:macro!inner!defining:
The \atcmd{M} (or~\atcmd{m}; see below) command denotes a \hl{\WEB\ 
macro}. \WEB\ 
macros have exactly the same syntax as C~macros (including arguments), 
but they are expanded when
\FTANGLE\ outputs the code. Just as in~C, the construction is expanded again
and again until nothing remains to be expanded. [The ANSI~C constructions
`\&\#' (``stringize'') and~`\&{\#\#}' (``token paste'') are supported, as
are certain extensions such as the ability to handle variable numbers of
arguments.] 
On input, the preprocessor understands all macros that have been defined up
to the current point in the file, so they can be used in statements such as
`\.{@\#if(MACRO)} \It{block\_of\_code} \.{@\#endif}' to selectively reject
or retain fragments of code.  Usually, \.{@m}~commands should appear in the
definition section, but they are also permitted in the code section, where
they are called \It{deferred macros}.  See the section on `Macros' for more
details. 

\@m(define a \WEB\ macro; mark macro name defined)[C,\oT] ^^:\>{@m}:
Equivalent to `\atcmd{M@[}'.  See the discussion about ``Forward
references'' below.

\@n(set language to \Fortran)[L,C,T,H] ^^:\>{@n}:
^^:language!setting!Fortran--77\actual\FORTRAN--77: 
The \atcmd{n}~command means \hl{set the 
current language to~\Fortran}. ^^{language!Fortran:\FORTRAN}
(See the more detailed discussion of
language commands for more information.) One may question the choice of
symbol here. Unfortunately, `\.f'~was already in use, denoting formatting;
hence, we use the \It{last} letter of the language name: fortra\.N, \.C,
ratfo\.R.  With no argument, \Fortran--77 is selected.  The command
\atcmd{n9}~selects \Fortran--90.

\@O(open new output file with global scope)[C] ^^:\>{@O}:
^^:file!output!opening new:
The \atcmd{O}~command \hl{changes the name of the output file} for tangled
code, during the output in phase~2.  At present, it may appear only in the code
section.  
White space is skipped after the~\atcmd{O}.  The next run of
non-white characters is interpreted as a complete file name, including
extension.  Any remaining text on the line is skipped.  The upper-case form
of this command has \It{global} scope---that is, the name change remains in
effect until the next \atcmd{O}~command, if any.  (The lower-case form has
local scope and is probably more useful; see below.)  At present, this
command has no effect for 
\FWEAVE.  The purpose of this command is to allow very large codes to be
tangled into several output files in cases where the compiler may have
limitations on the size of the source file it can process.

Note that since \atcmd{d}~commands are collected during phase~1, they are
at present oblivious to any~\atcmd{O} or \atcmd{o}~commands;
\atcmd{d}~definitions will always be written into the first file open for a
particular language.  (In the future, this may be generalized.)

\@o(open new output file with local scope)[C] ^^:\>{@o}:
^^:file!output!opening new:
The \atcmd{o}~command \hl{changes the name of the output file} for tangled
code, during the output in phase~2.  The rules are the same as for the
\atcmd{O}~command described above, except that \atcmd{o}~has \It{local}
scope.  That is, the command behaves in the same way as does a local
language change: output is diverted to the new file \It{for the duration of
the current section only}.  When the next section begins, output reverts to
the global output file, as known at the beginning of the first module.
The purpose of this command is to generate several different kinds of files
from a single source file.  For example, let the \WEB\ file be called
\.{test.web}.  Then one could say

{\codemode
@c
@ Demonstration of the \\.\{@o\} command.
@a
@o test.h
int i; // This code goes into \\.\{test.h\}.
\Par
@ The next code goes into \\.\{test.c\}.
@a
main()
\{\}
}

\@r(set language to \Ratfor)[L,C,T,H] ^^:\>{@r}:
^^:language!setting!Ratfor--77\actual\RATFOR--77: 
The \atcmd{r}~command means \hl{set the 
current language to~\Ratfor}. ^^{language!Ratfor:\RATFOR}
With no argument, \Ratfor--77 is selected.  The command \atcmd{r9}~selects
\Ratfor--90.  (See the detailed discussion of language commands for
more information.)

\@u(undefine an outer macro)[\oP,\oT] ^^:\>{@u}: ^^:macro!outer!undefining:
This command \hl{undefines an outer macro}.   
^^{macro!outer} 
It should be used in the definition part only. ^^{definition!part}
See the discussion of~\atcmd{d} for more discussion.

\@v(overload an operator)[\oP,\oT] ^^:\>{@v}: ^^:operators!overloading:
 The \atcmd{v}~command allows one to give \FWEAVE\ information about
\hl{operator overloading}, an important feature of both~\Cpp\ and
\Fortran--90.  The syntax of this command is ``\.{@v \It{new}\_\It{op}
"\It{replacement \TeX\ text}" \It{old}\_\It{op}}'' and is
described  in detail in the section on ``Operator overloading'' above.

\@W(overload an identifier)[\oP,\oT] ^^:\>{@W}: ^^:identifiers!overloading:
The \atcmd{W}~command allows one to change the appearance of identifiers.
This command has several variants:  ``\.{@W \It{identifier}
"\It{replacement \TeX\ text}"}'', ``\.{@W \It{identifier}
\\\It{newmacro}}'', and ``\.{@W \It{identifier} .}''.  These are described
in detail in the section on ``Identifier overloading'' above.

\@x(terminate commentary section; begin old material in change file)[L,H]
^^:\>{@x}: ^^:ignorable material!terminating: 
This terminates the opening commentary section of a 
file.  See the discussion of~\atcmd{z} below. ^^{commentary!invisible}

This command is also used in change files to begin the old material; see
the separate discussion of change files.

\@y(terminate old material in change file)[H] ^^:\>{@y}: This is used in
change files to terminate the old 
material and to begin the new material.  See the separate discussion of
change files. 

\@z(begin commentary section; end changed material)[L,H] ^^:\>{@z}:
^^{commentary!invisible} ^^:ignorable material!beginning:
If a file begins with~\atcmd{z} in its very first two
positions, everything up to and including a line beginning with~\atcmd{x} is
skipped.  This feature allows one to insert commentary such as date,
	author, etc.\ that will not be printed or otherwise processed.  

This command is also used in change files to end the changed material; see the
separate discussion of change files.

\@'(convert character to ASCII integer)[C] ^^:\>{@'}:
^^:ASCII!converting to:
A construction of the form ``\.{@'$c$'}'' \hl{converts the single
character~$c$ to an integer representing its ASCII value}.  The character
can be represented in any of the standard forms:  for example \.{'a'},
\.{'\\141'}, and~\.{'\\x61'} are all equivalent.  In~C and~\Cpp, the
character is converted into octal---e.g., \.{@'a'}~$\to$~\.{0141}. In the
\Fortran-like languages it is converted into an integer of base~10---e.g.,
\.{@'a'}~$\to$~\.{97}.  

\@"(convert string to ASCII)[C] ^^:\>{@""}:
^^:ASCII!converting to:
A construction of the form ``\.{@"$c_1c_2\dots c_n$"}'' \hl{converts each
character in 
the string to an integer representing its ASCII value}, returning a
construction appropriate for initializations in the current language.  In~C
or~\Cpp, the result is a string with the characters replaced by the
appropriate octal values---e.g., $\.{@"a\\376b\\n"} \to
\.{"\\141\\376\\142\\12"}$. 
For \Fortran-like languages, the implementation is experimental and subject
to change.  Presently, it works as follows.
First, the \atcmd{}~is stripped away, leaving the string.  If the value
of the style-file 
field \.{ASCII\_fcn} is the null string, then the string is unchanged.  If
\.{ASCII\_fcn} is not null, this field is used as the name
of a function to be called with the ASCII string as argument.  Thus, the
default value of \.{ASCII\_fcn} is \.{"ASCIIstr"}.  Unless this is changed
in the style file, then in \Fortran\ the command ``\.{@"a\\376b\\n"}'' will
tangle to ``\.{ASCIIstr('a\\376b\\n')}''.

\@{[}(mark next identifier as defined here)[C,H] ^^:\>{@[}: 
^^:identifiers!marking as defined:
This command has two uses.  First, if it appears in a 
change file in the first two positions of the line, it signifies a shift
into code mode; see the separate discussion of change files.

Otherwise, it says that the next \It{non-reserved} identifier should be marked
as being defined in this section.  Identifiers thus marked are subscripted
^^{subscripts, module number}
in the woven output with the number of the section in which they were
defined.  Usually, the identifier is a function name.  When \FWEAVE's
syntax analyzer recognizes a function in phase~2, it marks the function
name automatically.  However, only subsequent references to that function
are marked.  Additional mechanisms exist to handle the problem of forward
referencing.  For example, the commands~\atcmd{a}, \atcmd{d}, and~\atcmd{m}
issue implicit~\atcmd{[}s. See the more detailed discussion about ``Forward
references to identifiers'' in the section on ``Additional Features'' below.

\@](shift out of code mode)[H] ^^:\>{@]}: This command also has two uses.
If it appears in a 
change file in the first two positions of the line, it signifies a shift out of
code mode; see the separate discussion of change files.

(Otherwise, its use is experimental and not supported yet.)

\@`(\It{reserved})[C,H] 
\It{This command is experimental.  Please do not use.}

\Knuth
\@<(begin a module name)[C,\oT] ^^:\>{@<}: ^^:module!name!beginning:
A \hl{module name} begins with~\atcmd{<} followed by ^^:module!name:
\TeX\ text followed 
by~\atcmd{>}; the \TeX\ text should not contain any \.{WEB} control sequences
except~\atcmd{@}, unless these control sequences appear in \[code\] text that
is delimited by \pb. The module name may be abbreviated, after its first
appearance in a \.{WEB} file, by giving any unique prefix followed by
`\.{...}', where the three dots immediately precede the closing~\atcmd{>}. No
module name should be a prefix of another. Module names may not appear in the
definition part of a module (since the appearance of a module name ends the
definition part and begins the \[code\] part). \[There are two exceptions
to this last rule: first, a module name may appear immediately after an
\atcmd{f} command, thereby allowing module names to be formatted. Second,
you may use the construction \.{\#<\dots@>} ^^{\>{\PM<...@>}} in a \WEB\
macro definition to stand for a module name.\]
\endKnuth

\@{/*}(begin long verbatim comment)[C] ^^:\>{@/*}: ^^:comment!long!beginning:
This denotes a long \hl{verbatim comment}  
^^:comment!verbatim: ^^{comment!long}
(terminated by~`\.{*/}'). 
The idea is that while \TANGLE\ generally throws away all comments,
stripping down the output to a bare minimum, retaining some comments in the
output may be helpful for debugging purposes. Therefore, one is allowed to
preface ordinary C-style comments with an \atcmd{}; such comments will be
passed through to the output. For~\C, the comment is literally just passed
along; nothing else happens. For the other languages, care is taken to
generate a valid comment line. This is particularly annoying for \Fortran--77,
which does not have the notion of a trailing comment. There, trailing
verbatim comments are moved to the next line (essentially the inverse of
what the input driver does). Incidentally, module numbers are automatically
inserted as verbatim comments into the program, in order to help correlate
the outputs of \.{WEAVE} and \.{TANGLE} (see Appendix~C\null). To make all
comments verbatim, use the command-line option `\.{-v}' or put the
command~`\.{+v}' into your \.{.fweb} file.  ^^{\>{-v}}

\@{//}(begin short verbatim comment)[C] ^^:\>{@//}:
^^:comment!short!beginning: 
A short \hl{verbatim comment} (terminated by an 
end-of-line). ^^{comment!verbatim} ^^{comment!short}

\@\%(ignorable comment)[L,T,C]  ^^:\>{@\PC}: ^^:comment!ignorable:
\hl{Ignorable comments} are \FWEB's analogs to \TeX\
comments: Everything from the \atcmd{\%}~command to and including the next
newline is ignored, for both \FWEAVE\ and \FTANGLE.  Thus, this comment
does not appear as part of the \FWEAVE's typesetting, in either the \TeX,
definition, or code part.  It can be useful for hiding text that might be
used in conjunction with special editors.  It can also be used to suppress
unwanted newlines that sneak into module definitions.  Those generally
begin and end with a newline, as indicated:

{\codemode
@<\dots@>=\It{newline}
\Tab .
\Tab .
last line of module\It{newline}
}
\noindent Especially in \Fortran-77, those newlines may prevent the use of
the module name as a component of a longer line, for example as an argument
list of a function:

{\codemode
\Tab function f(@<Args@>)
}
\noindent To ensure that this example tangles correctly, say

{\codemode
@<Args@>=@%
a,b,c@%
}

\comment
Also, if this command is encountered in
a \TeX\ part, it ends that part and starts the definition section.  An
ordinary comment on the next line will then be formatted properly.
(Otherwise, the comment would be treated as part of the \TeX\ part and
formatted less desirably.)  Thus, if you wish to begin a definition part
with a comment, say

{\codemode 
@ TeX documentation.  
@% (Any text here is completely ignored.)
// This comment is formatted properly. 
@m ...  
}
\endcomment

\@?(compiler directive)[C] ^^:\>{@?}: ^^:compiler directives!beginning:
This command begins a one-line \hl{compiler directive}. 
\FTANGLE\ constructs an output line by first outputting the contents of the
style field \.{cdir\_start.$l$}, where $l$~is the identifier character for
the current language.  Then it copies everything between the~\atcmd{!} and the
next newline.  Consider the C~language as an example.  By default,
\.{cdir\_start.C} is set to \.{"\#pragma\ "}.  Then the command
`\atcmd{?help}' is output as ``\.{\#pragma\ help}''.

\@!(compiler directive)[C] ^^:\>{@"!}: ^^:compiler directives!beginning:
This is an obsolete form of~\atcmd{?}.  It differs in the way that the text
following the command is processed.  For~\atcmd{!}, that text is just treated
as one big string.  For~\atcmd{?}, the text is broken up into tokens.  The
advantage of this is that argument substitution can occur when \atcmd{?} is
used in a \WEB\ macro definition.

\@{(}(begin meta-comment)[C] ^^:\>{@(}: ^^:comment!meta-!beginning:
The beginning of a ``\hl{meta-comment},'' ^^{comment!meta-} i.e.,
commented-out code-section material that is supposed to appear in the
output file, is indicated by \atcmd{(} in the \.{WEB} file.  (Place this
command in column~1.)  {\bf Note that
the behavior of this command has been changed beginning with version~1.30.}
For both processors, this command provides a verbatim channel directly to
the output; it behaves as a generalized comment.  Its operation is
controlled by several style-file parameters.  For \FTANGLE, these are
\.{meta.top.$l$}, \.{meta.prefix.$l$}, and \.{meta.bottom.$l$}, where
$l$~is a language symbol such as~`\.{N}' for \Fortran.  By default, these
are defined to generate valid comments for each particular language.  For
example, the C~defaults are \.{meta.top.C = "/*"}, \.{meta.bottom.C =
"*/"}, and \.{meta.prefix.C = ""}.
If they are defined in the style file, then the body of text
between~\atcmd{(} and~\atcmd{)} is preceded by the contents of \.{meta.top}
and followed by the contents of \.{meta.bottom}.  Each line of the body of
text will begin with the contents of \.{meta.prefix}.  Experiment with an
example to see just what happens.  For \FWEAVE, the parameters are
\.{meta.begin} and \.{meta.end}; these are defined by default to set up
appropriate verbatim environments to surround the body of text.  For
example, in \LaTeX\ (when the `\.{-PL}'~option is used)
they bracket the text with \.{\\begin\{verbatim\}} and
\.{\\end\{verbatim\}}.  

This command may be useful when converting pre-existing \Fortran\ codes
with comments designed without regard for \TeX's conventions.  The verbatim
environments will not destroy vertical alignment, nor will they complain
about the use of special symbols such as~'\.{\$}'.  However, please use
this command only as a last resort.  For pretty alignments, use \TeX's
alignment features (e.g., \.{\\halign}) inside a standard \WEB\ command.
If you want to temporarily comment out a section of code, it is best to use the
preprocessor commands~\atcmd{\#if} and~\atcmd{\#endif}.  

\@)(end meta-comment)[C] ^^:\>{@)}: ^^:comment!meta-!ending:
 The end of a ``meta-comment'' is indicated by~\atcmd{)}. (Place this
command in column~1.)

\@\{(suppress breakpoint comment)[C] ^^:\>{@\LB}: ^^:breakpoint
command!suppressing insertion of:
In debugging mode (which means when the \.{\_BP} macro 
has been defined from the command line; see discussion below), this command
is used to replace the opening brace of a module, and means to suppress the
default insertion of a breakpoint command just after that brace. This is
necessary in C~code when the brace is followed by declaration statements.
To insert the breakpoint later, use~\atcmd{b} at the desired location.

\Knuth
\@\AM(join two items)[C] ^^:\>{@\amp}: ^^:joining: 
The \hl{\.{@\&} [\It{join}] operation}  
causes whatever is on its left to be adjacent to whatever is on
its right, in the \[code\] output. No spaces or line breaks will separate
these two items. However, the thing on the left should not be a semicolon,
since a line break might occur after a semicolon.  \[(See also the
\atcmd{+}~command.)\] 
\endKnuth

The \It{join} operation should be distinguished from the macro processor's
\It{paste} operation (\.{\#\#}). Pasting ^^{pasting}
abuts two things, then \It{retokenizes} the result to obtain a single new
identifier. Joining simply prevents a space from appearing between two
objects on output. The difference can be very significant in macro
processing, where the new identifier that results from the paste might be a
macro subject to further expansion.  In general, the join operation should
not be used within \WEB\ macro definitions.

\Knuth
\@\^(index entry in Roman type)[C,T] ^^:\>{@\^}:^^:text!control: 
^^:index!entry!Roman type: 
The ``\hl{control text}'' that follows, namely everything up to the
next~\atcmd{>}, will be  
entered into the index together with the identifiers of the program; this
text will appear in Roman type.  ^^{fonts!Roman} For example, to put the
phrase ``system dependencies'' into the index, you can type `\.{@\^system
dependencies@>}' in each module that you want to index as system-dependent.
A control text
\bdots\ must end on the same line of the \.{WEB} file as it began.
Furthermore, no \.{WEB} control sequences are allowed in a control text,
not even~\atcmd{@}. (If you need an \atcmd{}~sign you can get around this
restriction by typing `\.{\\AT!}'.) ^^:\CS{AT"!}:

\@.(index entry in typewriter type)[C,T] ^^:\>{@.}: 
^^:index!entry!typewriter type: 
 The ``\hl{control text}'' that follows will be entered 
into the index in \.{typewriter} \.{type}; ^^{fonts!\>{typewriter}} see the
rules for \atcmd{\^}, which is analogous.

\@9(user-defined index entry)[C,T] ^^:\>{@9}: ^^:index!entry!user-controled
format:  
 The ``\hl{control text}'' that follows will be entered 
into the index in a format controlled by the \TeX\ macro~`\.{\\9}', which
the user should define as desired; see the rules for~\atcmd{\^}, which is
analogous.  The reference would be made as follows: \.{@9wildcard
reference@>}. If you wanted your wildcard reference to appear in {\ss
sans serif} type, you would define~\.{\\9} like this:
\.{\\def\\9\#1\{\{\\tenss\#1\}\}}. (In earlier versions of \WEB, this command
was called~\atcmd{:}. However, that is now the pseudo-colon, and although
\.{@9}~may not look as pretty, it should be easier to remember.)

\@t(format control text)[C] ^^:\>{@t}: ^^[text!control!putting into hbox]
The ``\hl{control text}'' that follows, up to the next~\atcmd{>}, will be
put into a \TeX\ \.{\\hbox} and formatted along with the 
neighboring program. This text is ignored by \.{TANGLE}, but it can be used
for various purposes within \.{WEAVE}. For example, you can make comments
that mix \[code\] and classical mathematics, as in `$\\{size}<2^{15}$', by
typing `\.{|size < @t\$2\^\{15\}\$@>|}'.  A control text must end on the
same line of the \.{WEB} file as it began, and it may not contain any
\.{WEB} control codes.

\@=(verbatim control text)[C] ^^:\>{@=}: 
^^:text!control!passing verbatim to output:
The ``\hl{control text}'' that follows, up to the next~\atcmd{>}, will be
\hl{passed verbatim} to the program. 


\@\_(underline index entry)[C,T] ^^:\>{@\_}: ^^:index!entry!underlining:
The module number in an index entry will be underlined 
if \atcmd{\_}~immediately precedes the identifier or control text being
indexed. This convention is used to distinguish the modules where an
identifier is defined, or where it is explained in some special way, from
the modules where it is used. A~reserved word or an identifier of length
one will not be indexed except for underlined entries. An~\atcmd{\_} is
implicitly inserted by \.{WEAVE} \[when an identifier is being defined or
declared---for example, when \WEAVE\ recognizes a function, or in type
specification statements such as \&{integer} \|i,~\|j\].  It is also
inserted implicitly just after~\.{@d}, \.{@m}, and~\.{@f}.  Because of
these implicit insertions, one should rarely need to use \.{@\_}~explicitly.

\@-(delete index entry)[C] ^^:\>{@-}:
^^:index!entry!deleting:
An identifier that immediately follows an~\atcmd{-} will not appear in the
index.  

\@,(insert a thin space)[C] ^^:\>{@,}: ^^:insertion!thin space:
This control code inserts a \hl{thin space} in \.{WEAVE}'s output; 
it is ignored by \.{TANGLE}. Sometimes you need this extra space if you are
using macros in an unusual way, e.g., if two identifiers are adjacent.

\@/(line break)[C] ^^:\>{@/}:^^{line!break} ^^:insertion!line break:
This control code causes a
\hl{line break} to occur within a program formatted by \.{WEAVE}; it is
ignored by \.{TANGLE}. Line breaks are chosen automatically by \TeX\
according to a scheme that works
\[most\] of the time, but sometimes you will prefer to force a line break
so that the program is segmented according to logical rather than visual
criteria.  Caution: \atcmd{/}~should be used only after statements or
clauses, not in the middle of an expression; use~\atcmd{|} in the middle of
expressions, in order to keep \.{WEAVE}'s parser happy.

\@|(optional line break in expression [code text])[C] ^^:\>{@"|}: ^^{line
break!optional}  ^^:insertion!optional line break: 
In code text, this control code specifies an \hl{optional line break} in
the midst of  an expression. For example, if you have a long condition
between \&{if} and \&{then}, or a long expression on the right-hand side of
an assignment statement, you can use~\atcmd{|} to specify breakpoints more
logical than the ones that \TeX\ might choose on visual grounds.

In \TeX\ text, this command is instead a literal vertical bar.  See the
discussion above.

\@\#(line break plus white space)[C] ^^:\>{@\PM}:^^{line!break!with white
space} ^^:insertion!line break!with white space:
This control code forces a \hl{line break}, like \atcmd{/}~does, and it also
causes a little extra white space to appear between the lines at this
break. 
\endKnuth

\[\Levy: 
\WEB\ automatically inserts this extra space between
functions, between external declarations and functions, and between
declarations and statements within a function.\] \[Furthermore, \It{this
command is essentially equivalent to a blank line in your source file},
unlike the original convention of \WEB. You should have to use this command
very rarely, since blank lines are so much easier and prettier looking in
the source file.  It is good practice to insert blank lines liberally in
your source file anyway for readability. For example, it usually looks best
if you set off things like \&{if} statements by blank lines.\]

\noindent Note that `\.{\PR}' is also the prefix for the preprocessor
commands. No confusion arises, however; \WEB\ interprets things like
\Endif\ as single units. 

\Knuth
\@+(cancel line break)[C] ^^:\>{@+}:^^{line!break!cancelling} 
^^:insertion!line break!cancelling:
This control code cancels a 
line break that might otherwise be inserted by \.{WEAVE}.\ \bdots\ For
example, you might use this to force two statements to appear on the same
line, as in the \Fortran\ line 

{\codemode
a = b; @+ c = d
}
\noindent It is ignored by \.{TANGLE}.

\@;(pseudo-semicolon)[C] ^^:\>{@;}:^^:semicolon, pseudo-:
^^:pseudo-!semicolon: 
This control code, \[sometimes 
called a \It{pseudo-semi}\], is treated like a semicolon, for formatting
purposes, except that it is invisible. You \[should\] use it, for example,
after a module name when the code text represented by that module name
\[represents a complete statement\], since \[in the absence of an explicit
format statement
\WEAVE\ thinks module names are just expressions\].
\endKnuth

Some examples of the use of pseudo-semis are in order. The principal use of
them is after module names in certain situations. Consider the following
situation: ^^<semicolon, pseudo->

{\codemode 
@c 
@ Here is an example of the use of pseudo-semicolons.
@A
if(debug) @<Test@>@; // Use pseudo-semi here because @<Test@> ends with '\}'.
else @<Compute@>; // Use semi here because @<Compute@> does NOT end with ';'.
\Par
@ 
@<Test@>=
\stmt
\Par
@ 
@<Comp...@>= 
x = 1.0@; // Ends with a pseudo-semi so WEAVE will format it properly. 
}

\noindent The goal is to simultaneously fool \WEAVE\ into thinking that
you have written down a complete statement and to avoid introducing a
spurious semicolon where it doesn't belong. In particular, it would be
wrong (and would lead to a compiler error about an unmatched \&{else}) to
follow \.{@<Test@>} with a semicolon instead of a pseudo-semi, because the
definition of \.{@<Test@>} is already syntactically complete.

You may also need pseudo-semicolons to terminate macro definitions that are
not complete statements (but become one when they are terminated by a
semicolon in actual use). Some users feel annoyed at typing such
pseudo-semis; they feel they should be inserted automatically.
Unfortunately, they are not always necessary, and inserting extra ones will
typically at least insert an extra blank line in the output, possibly
worse. Nevertheless, the command-line option~`\.{-m;}' has been provided;
^^:\>{-m;}: this will append a pseudo-semi to all \WEB\ macro definitions.
However, use of this option is not recommended.

\@e(pseudo-expression)[C] ^^:\>{@e}:^^:expression!pseudo-:
^^:pseudo-!expression: 
The philosophy of the \It{pseudo-expression} is similar to that of 
the pseudo-semi. The pseudo-expression is treated like an expression (an
identifier is a simple expression) for formatting purposes, except that it
is invisible. It finds use in certain macro constructions that the syntax
analyzer would not otherwise recognize. For example, in~C the analyzer has
the rules $\hbox{\.*\It{expr}} \to \hbox{\It{expr}}$ and
$(\hbox{\It{expr}}) \to
\hbox{\It{expr}}$, but it doesn't understand the construction
`\.{(*)}', which occurs only very rarely in ordinary C~syntax (in certain
casts) but certainly might appear in unusual macro usage. The cure is to
use the pseudo-expression; \WEAVE\ will be happy if you say `\.{(*@e)}'.

\@:(pseudo-colon)[C] ^^:\>{@":}:^^:colon, pseudo-: ^^:pseudo-!colon:
The \It{pseudo-colon} is philosophically 
similar to both the pseudo-semicolon and the pseudo-expression: It's
treated just like a colon, except that it's invisible. It is useful in
formatting certain \&{case} constructions.  For example, consider

{\codemode
@<Special cases@>=
case 1:
case 2@: @;
}
\noindent The pseudo-colon is used so that one can later say ``\.{@<Special
cases@>:}'' when the module name is actually used.  The
pseudo-\It{semi}colon is used to terminate the module so that the syntax
analyzer can understand the entire construction as a statement and thus
format it properly.  

\Knuth
\parinsert{2}{6}{0.55}
``{\ssbf WEAVE's built-in formatting method is fairly good, but it is
incapable of handling all possible cases...}''

The last \[eight\] control codes (namely~\atcmd{,}, \atcmd{/}, \atcmd{|},
\atcmd{\#}, \atcmd{+}, \atcmd{;}\[, \atcmd{e}, and \atcmd{:}\]) have no effect
on the program output by \.{TANGLE}; they merely help to improve the
readability of the \TeX-formatted \[code\] that is output by \.{WEAVE}, in
unusual circumstances. \.{WEAVE}'s built-in formatting method is fairly
good, but it is incapable of handling all possible cases, because it must
deal with fragments of text involving macros and module names; these
fragments do not necessarily obey the syntax
\[of the source languages themselves\].  Although \.{WEB} allows you to
override the automatic formatting, your best strategy is not to worry about
such things until you have seen what \.{WEAVE} produces automatically,
since you will probably need to make only a few corrections when you are
touching up your documentation.

Because of the rules by which every module is broken into three parts, the
control codes~\atcmd{d}, \atcmd{f}, \atcmd{l}, \atcmd{v}, and~\atcmd{a} are not
allowed to occur once the \[code\] part of a module has begun. Note that
\atcmd{m}~\It{is} allowed (unlike in the original \WEB\ design); it
signifies a deferred macro definition.

The \WEB\ control codes are summarized in Appendix~L.  ^^)control codes)

\dsection ADDITIONAL FEATURES and CAVEATS.[12.21]

Here we collect a miscellany of features, warnings, and suggestions.

\newfeature
\Feature Extended character sets. \[In Knuth's  original memo, this
remark was about extended character sets. See the 
documentation for \.{common.web} for more information.\] ^^{character set}

\Feature It's best to use ASCII characters. ^^[ASCII!using]
If you have an extended
character set, all of the characters listed 
in Appendix~C of {\sl The \TeX book\/} can be used in strings. But you
should stick to standard ASCII characters if you want to write programs
that will be useful to  all the poor souls out there who don't have
extended character sets.

\Feature Numerical constants. Hexadecimal, octal, and binary constants are
allowed in all 
^^{constant!hexadecimal} ^^{constant!octal} ^^{constant!binary} languages,
generalizing the C-style format (which does not allow binary constants).
The syntax is \.{0x}$hhh$ for hexadecimal,
\.{0}$ooo$ for octal, or \.{0b}$iii$ for binary. Here $hhh$~stands for a
sequence of hexadecimal digits (0--9 and $A$--$F$), $ooo$~stands for a
sequence of octal digits (0--7), and $iii$~stands for a sequence of binary
digits (0 or~1). Of course, C~already recognizes hexadecimal and octal
constants, so for~C these are just passed through to the output unchanged.
In the other cases, the constants are converted (during tokenization in
phase one) to the appropriate integer. For example, in \Ratfor\ or
\Fortran\ each of
\.{0xF}, \.{017}, and \.{0b1111} is replaced by~15.

\Feature Special assignment and increment operators. In \Fortran\ and
\Ratfor,  the post-increment operators~`\.{++}' and `\.{--}'
^^:operators!post-increment: ^^:\>{++}: ^^:\>{--}:
and the compound assignment operators
^^:operators!compound assignment: ^^:\>{+=}: ^^:\>{-=}: ^^:\>{*=}: ^^:\>{/=}:
`\.{+=}', `\.{-=}', `\.{*=}', and~`\.{/=}' are allowed in
restricted contexts---namely, in simple assignment statements. These
operators translate as follows, where $x$~is anything allowed on the
left-hand side of an equals sign---for example, a subscripted expression:

{\codemode
\Tab x++; // -> `x = x + 1;'
\Tab x--; // -> `x = x - 1;'
\Tab x += expr; // -> `x = x + (expr);'
\Tab x -= expr; // -> `x = x - (expr);'
\Tab x *= expr; // -> `x = x*(expr);'
\Tab x /= expr; // -> `x = x/(expr);'
}
\noindent They are very useful at increasing the readability of your code.
They can also be used in the \Ratfor\ \&{for} statement. For example,

{\codemode
for(i++; i<100; i*= 5)
}

\noindent They cannot, however, be used in ways such as `\.{a(k++) =
b(i++);}', even though the analogous construction in~C is both legitimate
and often highly valuable. 
Furthermore, one must say `\.{i++}', not `\.{++i}', even though these would be
identical in~C when used stand-alone.  If one does not want these
constructions to be recognized, he may turn them off by the command-line
option~`\.{-+}'. ^^:\>{-+}:

\Feature Strings. ^^[strings]
Strings are delimited by single quotes (\Fortran), double quotes (C and
\Ratfor), or (in the case of certain built-in functions), by parentheses.
In order to continue quoted strings to another line,
^^[strings!continuing]
all lines but the last
must end with a backslash (just as one would define a lengthy \C~macro).
Parenthesized strings should not be explicitly continued, unless the
command-line option `\.{-(}' is used. ^^:\>{-(}:

By default, the continuation of the string begins in column~1 of the next
line.  \Fortran--90 introduces a different convention, in which the
continuation of the string may begin in an arbitrary column, but \It{must}
be preceded by the same continuation character (an ampersand in
\Fortran--90) that was used at the end of the previous line.  This is
neither required nor allowed in \FWEB's default continuation mode.
However, if the \Fortran--90 convention is desired, it may be turned on by
the command-line option~`\.{-\\}'.
^^:\>{-\BS}:
When turned on,
it operates for all languages, not just \Fortran--90.  As an example, the
following two lines of code are equivalent, both dealing with the string
\.{"12345"}. 

{\codemode
@n9[-n&]
@ The global language is Fortran--90, with free-form syntax.  
FWEB's default continuation convention is used.
@A
x = "123&
45"

// Now tell \\FWEB\\\space to use Fortran--90's continuation convention.
@n9[-n& -\\]
x = "123&
\Tab &45"
}

\Feature Breaking long strings. ^^[strings!breaking] ^^:strings!long:
\FWEAVE\ will break very long strings if necessary after embedded
commas, or after every so many characters. When it does so, it inserts a
backslash; this generally causes no confusion.

\Feature Breaking \TeX\ output lines. The \TeX\ file output by \.{WEAVE} is
broken into lines having, by default, at most 80 characters each. The
algorithm that 
does this line breaking ^^{line!breaking}
is unaware of \TeX's convention about comments following `\.\%' signs on a
line. When 
\TeX\ text is being copied, the existing line breaks are copied as well,
so there is no problem with `\.\%' signs unless the original \.{WEB} file
contains a line more than eighty characters long or a line with \[code\]
text in \pb\ that expands to more than eighty characters long.  (You may
not be likely to create such lines yourself, but certain processors that
create \WEB\ code automatically have been known to generate such long
lines.)  Such lines should not have `\.\%' signs.  If you run into trouble
here, you might try increasing the length of the output line by using the
command-line option ``\.{-yll$nn$}'', where $nn < 255$. ^^{output!file!line
length} 

\Feature Comments. In all languages, the preferred commenting style is that
of~C or 
\Cpp: \.{/*...*/} can be extended across newlines; \.{//...} is terminated
by a newline.
^^[commenting style] ^^[comments]
In principle, these can be placed anywhere; however,
see suggestion~a) in the following item.  Note that standard \Fortran\ uses the
`\.{//}'~operator for concatenation.  Therefore, in \FWEB\ the short
comment is not recognized unless the one of the command-line
options~`\.{-n/}' (\Fortran), `\.{-r/}' (\Ratfor), or~`\.{-/}' (both \Fortran\
and \Ratfor) is used. ^^{\>{-n/}} ^^{\>{-r/}} ^^{\>{-/}}
To allow both ^{concatenation} and short comments, ^^{comment!short}
the operator~`\.{\\/}' ^^{\CS{/}}
has been introduced as an alternative symbol for
concatenation.  Also, \Fortran--90 introduces the exclamation point to begin
a single-line comment.  However, this conflicts with \FWEB's standard use
of the point for the logical \hbox{\.{NOT}}.  By default, therefore, \FWEB\
will not 
recognize the exclamation point as related to comments in \Fortran--90
unless one of the command-line options~`\.{-n!}', `\.{-r!}', or~`\.{-!}' is
used; ^^{\>{-n"!}} ^^{\>{-r"!}} ^^{\>{-"!}}
it will, however, always recognize the construction~`\.{!!}' ^^:\>{"!"!...}:
as the beginning of a short comment.  Thus, each of the following four lines
produces the same output for both \FTANGLE\ and \FWEAVE.

{\codemode
@n9[-n& -!]
@
@A
x = y // z ! This is a comment.
x = y // z !! This is a comment.
@n9[-n& -n/]
x = y \\/ z // This is a comment.
x = y \\/ z !! This is a comment.
}

\Feature Translation of code text. \[Code\] text is translated by a
``bottom up'' procedure that 
identifies each token as a ``part of speech'' and combines parts of speech
^^{speech, parts of}
into larger and larger phrases as much as possible according to a special
grammar that is explained in the documentation of \.{WEAVE}. It is easy to
learn the translation scheme for simple constructions like single
identifiers and short expressions, just by looking at a few examples of
what \.{WEAVE} does (see the following paragraph), but the general
mechanism is somewhat complex because 
it must handle much more than \[code\] itself. Furthermore the output
contains embedded codes that cause \TeX\ to indent and break lines as
necessary, depending on the fonts used and the desired page width. For
best results it is wise to adhere to the following restrictions:

\yskip\itemitem{a)}Comments in \[code\] text should appear only after
statements or clauses; i.e., after semicolons, after reserved words like
\&{then} and \&{do}, or before reserved words like \&{end} and \&{else}.
\bdots

\itemitem{b)}Don't enclose long \[code\] texts in \pb, since the
indentation and line breaking codes are omitted when the \pb\ text is
translated from \[code\] to \TeX. Stick to simple expressions or
statements.

One can watch the translation in action by using the option~`\.{-2}' ^^:\>{-2}:
on \FWEAVE's command line. 
This will send to the terminal a detailed list of the actions \FWEAVE\
takes while combining parts of speech into phrases.  For example, the
simple C~program

{\codemode
main()
\{
x = y;
\}
}
\noindent will produce output something like the following:

{\codemode
Tracing after {l.} 8 (language = C):
  121: *expr +expr+ +\{+ expr... =="\\\{" "\\\\\{x\}"
    5: *+expr+ +\{+ expr...  =="\\\{" "\\\\\{x\}"
    1: *+fn_decl+ +\{+ expr +binop+...  =="\\\\\{x\}" "="
    3: *+fn_decl+ +\{+ +expr+ ;...  =="\\\\\{x\}" ";"
    6:  +fn_decl+*+\{+ +stmt+ +\}+ -ignore-  =="\\\}" "[force]"
  131: *+fn_decl+ -stmt+ -ignore-  \\"[force]$\{\}[[5]]$[force]$\{\}[[15]]
$[force]$\{\}[[10]]" "[force]"
   71: *+function- -ignore-  =="\\\\\{main\}" "[force]"
    0: *+function-  =="\\254" "\\\\\{main\}"
}
\noindent Each line begins with the number of the rule that was just
executed.  For example, rule~121 recognizes the combination~`\.{()}' as an
expression, and rule~71 recognizes that a function declaration
(`\.{main()}') followed by a complete statement (`\.{\{\dots\}}') is a
function.   The asterisk indicates the starting point for the next search
for a matching rule.  The leading and trailing plus and minus signs
indicate whether that particular part of speech begins or ends with math
mode (plus) or ordinary text mode (minus).  The last two quoted expressions
on a line 
are strings whose contents are the current translations of the last two
explicit parts of speech shown on the line.  (Some of the details of the
printed expressions are really intended for the developer of \FWEB\ and
need not be explained here.)  If all goes well, the last
line will 
consist of a single part of speech such as \\{function}; however, if there
is a rule missing or incorrect or if the source code syntax is invalid, the
final line may consist of a multitude 
of unreduced parts of speech.  Option~`\.{-1}' ^^:\>{-1}:
will print only such
unreduced scraps.  Such debugging can be turned on selectively by the
commands~\atcmd{1} or~\atcmd{2}, and turned off again by~\atcmd{0}.  
^^:\>{@0}: ^^:\>{@1}: ^^:\>{@2}:
(The \atcmd{0}~should be placed in a  section separate from the other
debugging commands.) 

\Feature Code within vertical bars. ^^{\>{"|..."|}}
Comments \[and \WEB\ macro definitions\] are not
permitted in \pb\ text. After a `\.|'~signals the change from \TeX\ text to
\[code\] text, the next~`\.|' that is 
not part of a string or control text ends the \[code\] text.  Thus, you can
say ``\.{|@c x || y|}'' but not ``\.{|@c x | y|}''.  To handle the intent of
the last example, you may say ``\.{|@c x ||| y|}''. ^^:\>{"|"|"|}:

\Feature Braces in comments. ^^{braces!nested}
A comment must have properly nested occurrences of left and right
braces, otherwise \.{WEAVE} \[will try to balance the braces to keep \TeX\
from fouling up too much.  Unfortunately, the scanning mechanism that is
used here is optimized for speed, not perfection, so \WEAVE\ will complain
about the legitimate construction ``\.{/* ...\$\\\{\$... */}'', for
example.  You may need to introduce \TeX\ macros to avoid such warnings.\]


\comment
\parinsert{1}{3}{0.65}
``Reserved words ... must appear entirely in lowercase letters in the
{\ssbf WEB} file.''
\endcomment

\Feature Reserved words. Reserved words of \[the individual languages, such
as \&{int} or 
\&{double precision}\]  must appear
entirely in lowercase letters in the \.{WEB} file; otherwise their special
nature will not be recognized by \.{WEAVE}.
^^{identifiers!reserved}
You could, for example, have a macro named
\\{DIMENSION} and it would not be confused with \[\Fortran's\]
\&{dimension}. \bdots 
\endKnuth

\Feature \Fortran\ keywords. ^^{keywords!Fortran:\FORTRAN}
However, \Fortran\ also has another class of words, namely keywords such as
\.{BLOCKSIZE} or~`\.{ERR} that are used only inside I/O~statements. In
\Fortran\ and \Ratfor, the upper-case versions of these words are treated
as reserved and will be formatted in a special way that makes the
I/O~statements look appealing. 

\Knuth
\Feature Formatting identifiers. ^^[formatting] ^^{\>{@f}}
The \.{@f}~feature allows you to define one identifier to act like another,
and these format definitions are carried out sequentially\bdots. However,
a given identifier has only one printed format 
throughout the entire document (and this format will even be used before
the~\.{@f} that defines it). The reason is that \.{WEAVE} operates in two
passes; it processes~\.{@f}'s and cross-references on the first pass and
does the output on the second. \[(Note that in~C one has the possibility of
defining additional types via the \&{typedef} command. ^^{\<{typedef}}
This essentially acts like an implicit~\atcmd{f}.)\] 
\endKnuth

\Feature Formatting module names. In fact, as we have already stated, one
can also format a \It{module name}.
^^{module!name!formatting}
By default, module names are interpreted as
expressions, but this is not always what is desired.  For example, one can
say

{\codemode
@f @<Common blocks@> common
}

\noindent and the parser will understand the use of \.{@<Com...@>} as a
type specification. Only the first slot of~\.{@f} is allowed to be a
module name; the second slot must always contain an identifier.

\Knuth
\Feature New reserved words. You may want some \.{@f}~formatting that
doesn't correspond to any 
existing reserved word. In that case, \.{WEAVE} could be extended in a
fairly obvious way to include new ``reserved words'' ^^{reserved words!new}
in its vocabulary.
\[For example, \WEAVE\ has already been taught to understand the identifier
\IF{Real} as an intrinsic function in Fortran. Note that a way of teaching
\WEAVE\ your own formats without recompiling is to include via~\.{@i} a
file including those format commands.\]
\endKnuth

\Feature Special array formatting. ^^[array!formatting]
Both \Fortran\ and~C have a somewhat vanilla-flavored syntax for array
elements---e.g., \.{f(i,j)} or \.{f[i][j]}.  In some physics applications
certain indices are preferred---e.g., they might be covariant or
contravariant----and it is useful to see this explicitly in the woven
output.  Also, some users are annoyed (with good reason) by the dual use of
parentheses in \Fortran\ to denote both function calls and array elements;
they prefer to see something like \.{f[i,j]} for a \Fortran\ array element.
Several features are available to help in this regard.

Usually the parentheses (\Fortran) or brackets (C) denoting array elements
are just passed through to the output by both \FTANGLE\ and \FWEAVE.
However, when the `\.{-W[}'~option is used, \FWEAVE\ inserts a special call
to the \TeX\ macro \.{\\WXA} ^^{\CS{WXA}}, with the array elements as
arguments.  By redefining the behavior of~\.{\\WXA}, a variety of special
effects can be achieved.  To be more precise, one shouldn't generally
modify the definition of~\.{\\WXA} itself, which is rather complicated;
rather, one should redefine \.{\\WARRAY}, ^^{\CS{WARRAY}}
which is called by~\.{\\WXA}.  See the following example.

Redefining \.{\\WARRAY} affects all array references.  
An even more general possibility is to use the \atcmd{W}~command ^^{\>{@W}}
to overload specific identifiers in different ways.  See the description
of~\atcmd{W} and the following example.
\HRULE
\typeset{demo4}
\HRULE

\Feature Forward references to identifiers.  ^^[forward references]
^^[references!forward] ^^[subscripts, module number] 
We have learned that \FWEAVE\
makes two passes through the source file in order to handle forward
references to module names---i.e., the situation in which a module name is
used before it is defined.  It is desirable to extend this feature to
various identifiers such as function names and macros.  The convention is
to automatically \It{subscript} such identifiers with the number of the
module in which 
they are defined.  (The format can be changed by refining the \.{fwebmac}
macro~\.{\\WIN}; see below.) If the identifier has been defined in the
current section, then the numerical subscript is replaced by a small bullet.

^^[functions!and forward referencing]
Implementing such a mechanism poses a difficult problem in general.  For
example,  function names are processed by \FWEAVE's syntax parser during
phase~2, so unless some special action is taken only function references
occurring \It{after} the  definition will be subscripted---in other words,
forward referencing would not work.  The most straightforward
way of solving this problem would be to make two passes through the
parser; however, this has been rejected as being too slow.  Nevertheless,
some partial solutions can be given.

First, one can force 
\FWEAVE\ to understand that an identifier is a function name by prefacing
it with the command~\atcmd{[}.  ^^:\>{@[}:
This command is executed during phase~1; it marks the name as being defined
in the current module.  Actually, it marks the first identifier it can find
that is 
not already known to be a reserved word, so the~\atcmd{[} may occur at the
very beginning of a function declaration.  This allows a further
convenience.  By default, the command~\atcmd{a} is equivalent to~`\atcmd{A@[}',
where \atcmd{A}~begins the unnamed module but does nothing else.  (Previously
in this manual, we have used~\atcmd{a} to begin the unnamed module; we now see
that that was a little white lie.)  Thus, the following three function
definitions are completely equivalent:

{\codemode
@ Explicitly mark the function name.
@A
void @[f()
\{\}
\Par
@ Explicitly mark the entire function name.
@A@[
void f()
\{\}
\Par
@ Rely on~`\.{@a}' to issue an implicit~`\.{@[}'.
@a
void f()
\{\}
}
\noindent Since the marks are executed during phase~1, forward referencing
is not a problem.
Thus, in the following code the references to functions~\\f and~\\g in
module~1 will be properly subscripted in the woven output.

{\codemode
@c
@ An example of a function with forward referencing.
@a
main()
\{
f();
g();
\}
\Par
@ Forward references to functions declared in the unnamed module are
handled with ease.
@a
void f()
{}
\Par
@ For named modules, one must mark explicitly if that is appropriate.
@<Special functions@>=@[
void g()
{}
}
\noindent Note that at present section names do \It{not} automatically
issue an \atcmd{[}~command, so we had to insert one explicitly in the above
example.  This restriction may be removed in future releases.

Macro references can also be subscripted.
The commands~\atcmd{d} and~\atcmd{m} ^^{\>{@d}} ^^{\>{@m}}
issue implicit~\atcmd{[}s by default, so
you should have to do nothing explicitly to have macro references properly
identified.  If you never want a particular macro reference to be subscripted,
use the upper-case commands~\atcmd{D} or~\atcmd{M}. ^^:\={@d}{@D}: ^^:\={@m}{@M}:

In C-like languages additional types can be created via the \&{typedef}
command. ^^{\<{typedef}}
In the original \CWEB\ design, \&{typedef}s were processed during phase~2,
so there was again a problem with forward referencing.  The implicit~\atcmd{[}
command now issued by~\atcmd{a} aggravates the difficulty, as seen in the
following example:

{\codemode
@c
@ 
@A
@<Typedefs@>@;
\Par
@ The user-defined type |MY_TYPE| isn't understood here yet when |typedef|s
are processed in phase~2.  
@a
MY_TYPE f()
\{\}
\Par
@
@<Typedefs@>=
typedef int MY_TYPE;
}
\noindent Not only is the \&{typedef} name \&{MY\_TYPE} not understood when
it is discussed in the text, the implicit~\atcmd{[} issued by~\atcmd{a}
will incorrectly mark~\\{MY\_TYPE} instead of~\|f as a function defined in
the current module. Therefore, \&{typedef}s are now partly processed during
phase~1 to the extent that the identifier being \&{typedef}ed is now marked
as a reserved word.  Since the subscripting of identifiers is done during
the output in phase~2, the above example will now work correctly.

Here is a typeset illustration that contains forward references to function
names, macro references, and \&{typedef}s:
\HRULE
\typeset{demo3}
\HRULE

When many macro references and/or \&{typedef} statements are in use, one
may in some cases actually be annoyed by the clutter of subscripts.
Several mechanisms are provided to selectively turn on or off the subscripts.
First, all subscripts can be turned off from the command line by the
option~`\.{-f}'.  ^^:\>{-f}:
Second, style file entries (see section on ``Advanced Features'' below)
serve as switches to enable or disable 
subscripting for certain types of identifiers, according to the following
table: 
$$\vbox{\halign{\.{#}\hfil&\ ---\ #\hfil\cr
mark\_defined.generic\_name&Something explicitly marked by~\atcmd{[}. 
[$\WINo00$]\cr 
mark\_defined.fcn\_name&Function names.  [$\WINo11$]\cr
mark\_defined.WEB\_macro&\WEB\ macro (\.{@m}). [$\WINo22$]\cr
mark\_defined.outer\_macro&Outer macro (\.{@d}). [$\WINo33$]\cr
mark\_defined.exp\_type&Something explicitly marked by~\.{@\`}. 
[$\WINo44$]\cr
mark\_defined.typedef\_name&A \&{typedef}-like statement in C-like
languages. [$\WINo55$]\cr 
}}$$
By default, \.{mark\_defined.generic\_name} and
\.{mark\_defined.exp\_type} are set to~1 (on); the others are set to~0
(off).  

Each of the above types of identifiers has a number, indicated in brackets.
This number is the first argument to the subscripting macro~\.{\\WIN}; 
^^{\CS{WIN}}
the second argument is the number of the module in which the identifier was
defined.  Thus, if the function~\\{fcn} was defined in module~38, the
output \.{tex} file produced by \FWEAVE\ will contain the phrase
``\.{\\\\\{fcn\}\\WIN1\{38\}}''.  The identifier number is used as an
argument to an \.{\\ifcase} statement, so the output format can be
different for different types of identifiers and can be controlled by the
user.  The default \.{fwebmac} macro~\.{\\WIN} subscripts all kinds of
identifiers with a bullet if they were defined in the current module.
Otherwise, the module number subscripts are typeset in the same style as
the bracketed numbers in the above table.  You may wish to experiment to
find an output format that is more informative or pleasing to your eye.

\Feature Spacing and macros. ^^[spacing]
Macros place unusual demands on \WEAVE. For example, suppose one defined

{\codemode
@m PLUS +
}
\noindent then attempted to use that macro in the expression ``\.{x\ PLUS\
y}''. This would tangle correctly and do what you want, but \WEAVE's output
would look like ``\|x\\{PLUS}\|y'', whereas what you really would like is
\hbox{``\|x\ \\{PLUS}\ \|y''}. This occurs because \WEAVE\ treats all normal
identifiers as expressions, and its rules tell it to simply concatenate
expressions (with no intervening white space). To help in situations like
this, \FWEAVE\ has a few extra 
reserved words that invoke special rules that insert extra spaces. These
words are \\{\$\_BINOP\_}, \\{\$\_COMMA\_},
\\{\$\_EXPR}, \\{\$\_EXPR\_}, \\{\$EXPR\_}, and \\{\$UNOP\_}. 
^^:\>{\dollar\UL BINOP\UL}: ^^:\>{\dollar\UL COMMA\UL}: ^^:\>{\dollar UNOP\UL}:
^^:\>{\dollar\UL EXPR}: ^^:\>{\dollar EXPR\UL}: ^^:\>{\dollar\UL EXPR\UL}: 
The underscores show where spaces will be inserted. You can format your unusual
macros to these words, as in

{\codemode
@f PLUS $_BINOP_
}
\noindent and your macro will then be treated as the proper part of
speech---either a binary operator, a comma, an expression, or a unary operator.

\Feature M4 built-in commands. ^^[built-in!\>{m4}] ^^{\>{m4}}
By default, \Fortran\ and \Ratfor\ do \It{not} understand the special
\.{m4}~preprocessor built-in 
commands: \undertext{\&{changequote}}, \&{define}, \&{divert},
\&{divnum}, \&{dnl}, \&{dumpdef}, \&{errprint}, \&{ifdef},
\undertext{\&{ifelse}}, \undertext{\&{include}}, \&{incr},
\undertext{\&{index}}, \undertext{\&{len}}, \undertext{\&{maketemp}},
\undertext{\&{sinclude}}, \undertext{\&{substr}}, \undertext{\&{syscmd}},
\undertext{\&{translit}}, and \&{undivert}. To make them understand \.{m4},
use the command-line option~`\.{-m4}'.
^^:\>{-m4}:
Because these commands are
essentially macros, which need not obey the \Fortran\ syntax, \WEAVE\ has a
very difficult time formatting arbitrary \.{m4} constructions. To help
\WEAVE\ out, the underlined commands in the above list 
have their arguments interpreted as
strings (delimited by balanced parentheses), and \WEAVE\ will format them
as such, in typewriter type. These strings are treated just
like other strings, except that
if they don't end on the same line, they don't have to be
continued by a backslash. (However, you have the option of changing the
default. For parenthesized strings only, if you use the command-line
option~`\.{-(}', then those strings must be continued by backslashes.)

Similar considerations about string arguments apply to the \FWEB\ built-in
commands \undertext{\&{\_COMMENT}}, \undertext{\&{\_ERROR}},
\undertext{\&{\_IF}}, \undertext{\&{\_IFELSE}}, and
\undertext{\&{\_LEN}}. 

\Knuth
\Feature More general spacing. ^^[spacing]
Sometimes it is desirable to insert spacing into  code that is
more general than the thin space provided by~\atcmd{,}. The \.{@t}~feature
^^{\>{@t}}
can be used for this purpose; e.g., \atcmd{t\\hskip 1in@>} will
leave one inch of blank space. Furthermore, \atcmd{t\\4@>} can be
used to backspace by one unit of indentation, since the control sequence
\.{\\4} is defined in \.{webmac} to be such a backspace. \bdots

\Feature Change file. ^^[file!change] ^^[change file]
\.{WEAVE} and \.{TANGLE} are designed to work with two input files,
called \\{web\_file} and \\{change\_file}, where \\{change\_file} contains
data that overrides selected portions of \\{web\_file}. The resulting merged
text is actually what has been called the \.{WEB} file elsewhere in this
report.

Here's how it works: The change file consists of zero or more ``changes,''
where a change has the form `\.{@x}$\langle$old lines$\rangle$\.{@y}$\langle$%
new lines$\rangle$\.{@z}'. 
^^:\>{@x}:^^:\>{@y}:^^:\>{@z}:
The special control codes \.{@x}, \.{@y}, \.{@z} must appear at the
beginning of a line; the remainder of such a line is ignored.
The $\langle$old lines$\rangle$ represent material that exactly matches
consecutive lines of the \\{web\_file}; the $\langle$new lines$\rangle$
represent zero or more lines that are supposed to replace the old. Whenever
the first ``old line'' of a change is found to match a line in the
\\{web\_file}, all the other lines in that change must match too.

Between changes, before the first change, and after the last change,
the change file can have any number of lines that do not begin
with~\atcmd{x}, \atcmd{y}, or~\atcmd{z}. Such lines are bypassed and not used
for  
matching purposes, except for the following special codes.
\endKnuth

In addition to \atcmd{x}, \atcmd{y}, and~\atcmd{z}, the language commands
\atcmd{c}, \atcmd{r}, \atcmd{n}, and~\atcmd{L\It{l}} are also allowed in the
change file, as are the commands \atcmd{[} and \atcmd{]}.
^^{\>{@c}} ^^{\>{@r}} ^^{\>{@n}} ^^:\>{@[}: ^^:\>{@]}:
All these commands must begin in column~1. The command
\atcmd{[} means switch into code mode; 
^^{code!mode} ^^{mode!code}
\atcmd{]} means switch out of code
mode. These latter commands are necessary only in \Fortran, but are crucial
there. Although modes switch back and forth automatically between free-form
and column syntax as the input driver reads sequentially through the \It{input}
file, that can't happen automatically for the \It{change} file, which consists
of isolated fragments of text that could match any line of the input file,
in either \TeX\ mode or code mode.  If you do not help out the change file,
the input driver will probably not interpret the syntax of the change file
in the same way as it does the source file, and lines that look identical
in the source files nevertheless won't match.

For example, if a \Fortran--77 source file contains the line

{\codemode
\Tab call open('datafile')
}
\noindent the following change file will replace that line with two new lines:

{\codemode
@n
@[
@x
\Tab call open('datafile')
@y
/* Here are the replacement lines: */
\Tab call open('newdatafile')
@z
}

\Knuth
This dual-input feature is useful when working with a master \.{FWEB} file
that has been received from elsewhere (e.g., \.{FTANGLE.WEB} or
\.{FWEAVE.WEB}), when changes are desirable to customize the
program for your local computer system. You will be able to debug your
system-dependent changes without clobbering the master \.{web} file; and once
your changes are working, you will be able to incorporate them readily
into new releases of the master web file that you might receive from time
to time.
\endKnuth

You specify the name of the change file on the command line; 
^^:file!change!name of:
it is the
second command-line argument that the parser can recognize as a file
name---i.e, that does not begin with a hyphen.  A default extension of
`\.{.ch}' is implied.  If you just say `\.{FTANGLE test}', you are talking
about the web file `\.{test.web}' with the null change file. If you
say `\.{FTANGLE test test}', you are talking about the web file
`\.{test.web}' and the change file `\.{test.ch}'. If you say `\.{FTANGLE
alpha.fweb beta.fch}', you are calling for the web file `\.{alpha.fweb}'
and the change file `\.{beta.fch}'. It is almost never necessary to deal
with nondefault file extensions.  (The range of default extensions can
be increased by entries in the style file.  See the following discussion of
the style file and of the command-line option~`\.{-e}'.)

\section INPUT.[13.4] ^^(input( ^^[driver!input]

It doesn't take much time attempting to fit the column-oriented \Fortran--77
syntax into the \WEB\ framework to realize the virtues of languages such
as~C, \Ratfor, or \Fortran--90 with free-form syntax. The present \FWEB\
design solves the problem of 
multiple, incompatible input syntaxes by introducing the concept of
\It{input drivers}. These are front ends that convert the incoming syntax
as quickly as possible  to a uniform syntax that the innards of \FWEB\
can understand.  Individual lines from the \WEB\ file are filtered through
the \It{input driver} appropriate to whatever language is in force at that
point. For~\C, that filter is essentially a unit operator; it presents to
\FWEAVE\ and \FTANGLE\ the same input line that it read in. At the other
extreme, however, for
\Fortran--77 the filter does much more work. Because of the possibility of
\It{continuation lines}, the filter must read ahead. If it finds a
continuation line, it concatenates it to the stuff already in the filter's
buffer. Finally, when it finds no more continuations, it \It{appends a
semicolon} to the logical line it has constructed, then presents this line
to the innards of \FWEAVE\ or \FTANGLE. The semicolon serves as the
end-of-statement delimiter, just as it does in~\C. Thus, the input line
presented to the processors has a standard form for all supported
languages, so it can be parsed in a standard way.

In fact, the \Fortran\ and \Ratfor\ drivers do even more things, especially
related to comments. These details will be described in the following
sections. Here, the point to remember is that your input file can pretty
well follow the conventions of whatever mode you're in at the moment: \C, \Cpp,
\Fortran, \TeX, or whatever.

\subsection \Fortran--77 input.^^[Fortran:\FORTRAN!input driver] 
	^^[input!Fortran:\FORTRAN--77]

\It{It is recommended that you do not use bare \Fortran\ for new
codes; use \Ratfor\ instead.} Another option is to use the free-form mode
of \Fortran--90.

^^[comment!Fortran:\FORTRAN]
Although the preferred commenting style is C-style, the \Fortran\ column-1
convention is retained for compatibility with existing code. These two
styles are fundamentally incompatible, and the \Fortran\ style is
definitely not recommended! Note that
trailing comments beginning with an exclamation point \It{will not work}!

\indent\.{x = y !This doesn't work in Fortran--77.}

\noindent This is a VAX extension that conflicts with the standard \WEB\
use of the exclamation point, as it is the input symbol for the logical
\hbox{\.{NOT}}. (See below.) If your 
source file already contains such comments, you must change them into
C-style ones. With the aid of a good editor, this can be done with just one
command repeated automatically.

Following the conventions of \Fortran--77, lines that begin with~'\.C',
'\.c', or~'\.*' are 
(short) comments (terminated by the end-of-line).  When the
option~`\.{-n/}' is in effect, these lines behave 
identically to ones beginning with~`\.{//}'.  Consecutive comments of the
same kind (long or short) are concatenated by the input driver.  Thus, the
construction 

{\codemode
/* A */ /* B */
C C
// D
* E
}
\noindent will be typeset into the two lines
{\WP\6
\WC{ A B }\6
\Wc{C D E}\6

}

Since the input driver concatenates successive lines of the same type, very
long effective input lines can be created.  Sometimes the associated buffer
overflows and \FWEB\ terminates with an error message.  Since that buffer
is allocated dynamically, one can use the `\.{-y}'~option to increase its
size; the error message explains how.

A comment that appears on
the line immediately after a statement or continuation line will be
attached to the previous line as a trailing comment. Generally, this is not
what you want; a comment beginning in column~1 probably belongs with the
next statement. One solution is to insert a blank line before the comment.
This puts a blank line in your woven output. If you don't want that, omit
the blank line and preface the comment by~\atcmd{/}.

The commenting rules are such that both \FTANGLE\ and \FWEAVE\ will handle
^[compiler directives] appropriately. Typically a compiler directive begins
with the character~'\.C' so it will be ignored by a compiler that doesn't
understand the directive. Thus if \.{cdir}~is a compiler directive, one can
say ^^<compiler directives>

{\codemode
\Tab x = y
\Par
cdir Text of the directive
\Tab (more code)
}
\noindent and the compiler directive will be executed. Note the important
blank line before the directive. If it were not there, the directive would
be treated as a trailing comment attached to the previous line of code.
(It is instructive to try this example with the blank line both present and
absent. With the blank line absent, you will find that the~'\.d'
of~\.{cdir} gets eaten. This occurs because of a quirk of the input driver
that will be fixed someday.)  However, for new codes a much better
solution for compiler 
directives is to use the \atcmd{?}~command; see the discussion in the
section on control codes.

\parinsert{2}{7}{0.55}
``By default the semicolons are actually appended as {\bfit
pseudo-semicolons}, so they will be invisible on output.''

The \Fortran--77 input driver recognizes the end of a valid statement when the
next line is neither a continuation nor a comment. At this point, the input
driver performs a scan over everything it has collected so far and
concatenates any adjacent comments of the same type.  It then
\It{appends a semicolon} to the end of the compilable part of the statement
(i.e., just before the last comment), because the semicolon is used as a
universal statement terminator in the innards of \FWEAVE\ and \FTANGLE.
Logically, the semicolons should show up in the woven output, since they
are \FWEB's way of terminating statements.  However, this makes the
\Fortran\ output look a little strange, and, logic notwithstanding, people
have understandably found this annoying.  Therefore, by default the
semicolons are actually appended as
\It{pseudo-semicolons}, so they will be invisible on output.  To make the
semicolons 
visible, use the command-line option~`\.{-np}'.  \FTANGLE, of course, always
throws the semicolons away during its output phase, since they would not be
understood by the compiler.

If you think the \Fortran\ input driver isn't working the way it's supposed
to (for example, if it doesn't concatenate continuation lines properly),
you might want to look at the line-by-line output from the driver. You can
turn on this debugging feature with the command-line option `\.{-l}'. 
^^:\>{-l}:
If this confirms that something is wrong, by all means report the bug. The
\Fortran\ driver is much too complicated for its own good!  (Often, bugs
show up in incorrect continuation lines.  These can often be circumvented
by using the \.{-\#}
^^{\>{-\PM}}
option to remove the line- and module-number comments.)

If all goes well and \WEAVE\ is able to recognize a complete main program,
function, or subroutine, the body of that program unit is indented.
To be consistent, you should use the \&{program} statement for main
programs; otherwise, the indentation may appear strange. (You may
call this a bug, but it's really a design ``feature''.)

^^[input!alternative operators for]
\Fortran\ contains such archaic constructions as `\.{.ne.}'. \WEB\ has two
ways of helping you to deal with these things. You are allowed more
flexibility in input, and \WEAVE\ substitutes prettier constructions such
as `$\neq$' as it typesets the documentation. (The exact form of the output
is controlled by a \TeX\ macro; study \.{fwebmac.web}. Thus, if you don't
like the way exponentiation is typeset, for example, you can easily change
it without recompiling \FWEB.) 
\input dots

A few restrictions or modifications of \Fortran's rules have been made in
the interest of 
simplicity. First, \FWEB\ recognizes identifiers in a slightly different
way than does \Fortran. As an extension compatible with \Ratfor\ and~\C,
identifiers may contain underscores and dollar
signs and may be of arbitrary length. (\FTANGLE\ can
translate these to garden-variety \Fortran\ identifiers; see the discussion
of the \.{-t}~option. ^^{\>{-t}}
On the other hand, as a restriction
there may not be any white space within identifiers.
(However, \FWEAVE\ will correctly understand \&{go to}, \&{else if}, 
\&{end if}, and \&{end do}.) 
Secondly, there are a few cases in \Fortran\ where the same identifier is
allowed to be used in two entirely different ways. Perhaps the most
prominent case is the identifier \.{real}, ^^{\<{real}}
which is used both as a type
specification and as an intrinsic function. \FWEAVE, not being as
intelligent as the \Fortran\ compiler, does not understand enough about the
syntax to properly distinguish these two uses; specifically, it understands
\.{real} only as a type specification. In cases such as this, one can often
make \FWEAVE\ happy by recalling that \FWEAVE's reserved words are all in
lower case, but that \Fortran\ is case-insensitive. Thus, \Fortran\ doesn't
care whether you type \.{real} or \.{Real}, but \FWEAVE\ will not confuse
\\{Real} with a type specifier. In fact, for this particular case \FWEAVE\
has been taught to understand that \\{Real} is an intrinsic function, so
what you will really get is
\&{real} and \IF{Real}.  
As a matter of good programming style,
you just shouldn't get into this situation if you can avoid it. Don't, for
example, use \\{Integer} as the name of a function, even though \Fortran\
allows that and \FWEAVE\ will treat it as an ordinary identifier.

Standard \Fortran--77 does not understand the unnumbered block \&{do}
construction, which is a VAX extension. \FTANGLE\ understands such
constructions, and can optionally 
convert them into standard numbered \&{do}s. See the description of the
command-line option `\.{-d}'. (This mode is slow, and is not recommended.
Use \Ratfor\ or \Fortran--90 instead.)
^^:\>{-d}:

^^{declarations!\<{common}}
An excellent application of named modules is to define things like \&{common}
declarations that you wish to insert at the beginning of every subroutine.
By using a named module, you can keep the code for the common declarations
in the same file as the rest of your code; a separate include file is
unnecessary. 

One of the annoying \Fortran\ constructs is the ``dot constant''---e.g.,
`\.{.false.}' or~`\.{.eq.}'.  ^^:constant!dot:
In some cases \FWEB\ gets confused by the
periods, which are used for other purposes as well.  For example, a VAX
extension uses periods to separate components of structures.  (\Fortran--90
uses~`\.{\%}' for this purpose.)  If you want, you can change the delimiters
of such dot constants via the style-file options \.{dot\_constant.begin}
and \.{dot\_constant.end}.
^^{style file!vocabulary!\>{dot\UL constant.begin}} 
^^{style file!vocabulary!\>{dot\UL constant.end}}
For example, if you say in \.{fweb.sty} ^^{\>{fweb.sty}}

{\codemode
dot_constant.begin '['
dot_constant.end ']'
}
\noindent then you can say in your code things like
``\.{if(a[eq]b)\dots}''.  However, generally it is better to say
``\.{if(a==b)\dots}''.  The command-line option~`\.{-.}' tells \FWEB\ to
not attempt to identify dot constants (even when the delimiters have been
changed as above).  Use this option if your compiler uses periods for
something else. 

\subsection \Fortran--90 input. ^^[input!Fortran--90:\FORTRAN--90]

\Fortran--90 permits two input syntax styles:  column format, as in
\Fortran--77, and free-form format.  The column format behaves as in
\Fortran--77; see the previous subsection.  The free-form format is a great
advance, and should be used for new code.  The following remarks pertain to
free-form input.

In free-form input, lines are continued by a character at the \It{end} of
the line instead of one in column~6 of the next line.  
The ^:continuation character: is selected by a command-line option, which also
serves to turn on the free-form input mode.  You may choose either
`\.{-n\&}' or~`\.{-n\\}', ^^{\>{-n\amp}} ^^{\>{-n\BS}}
allowing one to continue lines with either an
ampersand (\Fortran--90's rule) or a backslash (compatible with~C and other
\WEB\ conventions).  (If you select~`\.{-n\\}',
\FTANGLE\ will convert the backslash into an ampersand on output.)
For example, here is how to begin a \.{web} source code written with
free-form \Fortran--90:

{\codemode
@n9[-n& -n/]
\Par
@* INTRODUCTION.  The following code will be in free-form Fortran--90.
(It may take a lot of CPU time.)
@a
program main
integer i
\Par
i =&
    0 // Illustration of line continuation.
iterate: do
	i++
	end do iterate
\Par
end
}

\subsection \Ratfor\ input. ^^[input!Ratfor:\RATFOR]

By default, the auto-semi mode is not used. In this case the
\Ratfor\ syntax is completely free-form and identical to that of~C.
In the auto-semi mode
^^{mode!auto-semi}
the input driver will turn  the \Ratfor-style comment
(anything between~`\.{\#}' and the end-of-line) into a C-style comment.
('\.{\#}'~characters embedded in comments will just be copied, and paste
tokens~(`\.{\#\#}') in \WEB\ macro definitions will be properly understood.)
As described earlier, in that mode it also
handles the \Ratfor\ style of obvious continuation, and supplies
semicolons in the appropriate places.

With the exception of remarks specific to \Fortran's
line-and-column-oriented syntax, all the other remarks about \Fortran\
apply to \Ratfor\ as well.

\subsection C and \Cpp\ input. ^^[input!C] ^^[input!C++]

This is the bare-bones driver; it does nothing but pass the free-form
syntax along to the innards of the processors. This driver is also used for
\Ratfor. 

Beginning with version~1.21, \&{typedef}ed variables ^^{\<{typedef}}
can be marked automatically with the number of the module in which they are
defined.  See the previous discussion of ``Forward References.''

One formatting annoyance is concerned with constructions of the form

{\codemode
typedef struct weird
\Tab \{
\Tab ...
\Tab \} weird;
}
\noindent The C~language permits this construction, in which \\{weird} is used
in two ways.  However, \WEAVE\ is not as clever as a compiler; it only
understands one interpretation of a variable, and will likely become slightly
confused by the above situation.  It's not really good programming practice
to use an identifier in more than one way anyway; replace the last
\\{weird} by \\{WEIRD}, or the first \\{weird} by \\{weird0}.

^^)input)

\section COMMAND-LINE OPTIONS.[14.3] ^^(options!command-line(

^^[command line!options] ^^[syntax rules!command line]
Various information of interest to \FWEAVE\ and/or \FTANGLE\ may be entered
from the command line. Command-line arguments are delimited by spaces; if
you need a space inside an argument itself, surround the argument with
quotes (single or double, depending on your operating system or shell).
Since the arguments are case-sensitive, remember that 
under VAX/VMS arguments are translated into lower case
unless they are protected by double quotes.  Under \Unix, certain characters
such as ``\.{\&|;<>()\{\}*?[]}'' may mean special things to the shell
^^{shell, special characters for} and may need to be escaped with a
backslash or protected with quotes.  Thus, while under VMS a valid option
is `\.{->}', under \Unix\ you must say `\.{-'>'}' or~`\.{-\\>}'.  (Since this
is cumbersome to type, the synonym~`\.{-=}' has been provided.)

\parinsert{3}{4}{0.5}
``Command-line arguments may appear in any order.''

Command-line arguments ^^[command line!arguments]
may appear in any order; they are processed from left to right.
If a command-line argument does not begin with a hyphen, it is understood
to be a file name.   The first file name found is the name of the \WEB\
source file; 
optionally, if a second file name is found, it is the name of the change file.
If the name (excluding a possible path)
contains a period, then it is processed exactly as specified.
Otherwise, \WEB\ supplies an extension. Precisely how this is done depends
on whether the `\.{-e}'~option is in effect.  If it is not in effect, then a
default extension is used:  ``\.{.web}'' for the \WEB\ file,
``\.{.ch}''~for the change file.  If it is in effect, then  extensions 
taken  from the relevant style file entry (\.{ext.web} or \.{ext.change})
are applied in turn until one matches. A
lone hyphen~`\.-' is understood to stand for the special file \.{stdin}
^^{\>{stdin}} 
(standard input),
which is usually the terminal.  Hyphenated options should have no space
between the option and its parameter, if one is required.
Thus, an example of a command line is

{\codemode 
fweave test test -wmy_macros
}
\noindent which means ``Weave the file \.{test.web} using the change file
\.{test.ch}; print `\.{\\input my\_macros}' at the beginning of
\.{test.tex}.''   It would be an error if \.{test.web} were missing.
However, if one had said in the style file ``\.{ext.web = "web\ wb"}'' and
used the `\.{-e}'~option, then in the absence of \.{test.web} the system
would attempt to open \.{test.wb}.  This same mechanism works for file
names specified on \.{@i}~lines (see the discussion of the control
code~\atcmd{i}, except that if the `\.{-e}'~option is not in effect there
are no default extensions.  The associated style-file entries are
\.{ext.hweb} for the included web file and \.{ext.hchange} for the
associated change file.

Certain command-line options can be negated by including an extra hyphen.
^^[command line!options!negating]
For example,

{\codemode
fweave test --x
}
\noindent means ``Do the opposite of option `\.{-x}'.''  Since
`\.{-x}'~means suppress all cross-reference information, `\.{--x}'~means
``\It{do} write all cross-reference information.''  
^^{cross-references!printing} ^^{cross-references!suppressing}
This example is essentially pedagogical, 
since that information is normally written anyway by default.  The most common
reason to negate an option is when one wishes to override an option that
was set in the initialization file~\.{.fweb} (discussed below).  For
example, \.{.fweb}~might contain 
the command~`\.{+v}', which tells \FTANGLE\ to make all comments verbatim
and pass them along to the output file.  If you want to turn off those
comments for one particular run, say `\.{--v}'~on the command line.

\subsection Options to language commands. 

Whenever a language is changed via a control code such as~\atcmd{c}, that code
may be optionally followed by text, optionally enclosed in square brackets.
This was explained in the section on languages.  The optional text is
essentially parsed as though it were a command line; this affords a way
of selecting different parameters for each language.  For example, the
following are valid commands:

{\codemode
@c++ @% Select c++.
@r[-k*] @% Select Ratfor, and suppress comments about keyword expansions.
}
\noindent However, some options such as~\.{-x} are truly global and are not
reasonably changed in the midst of the \.{web} source.  Those global
commands that may \It{not}
be used inside brackets are marked in the following list with asterisks.

\subsection List of options.

Here are the options (brackets mean optional arguments; case is significant):
\clo{
-&^^:\>{-}: The file name ``\.{stdin}'', ^^{\>{stdin}}
 which signifies ``standard input''. ^^{input!standard}\cr
-0&^^:\>{-0}: Turn off \WEAVE's debugging output.  (The command~\atcmd{0}
 should be placed in a different module from~\atcmd{1} or~\atcmd{2}.)
^^:debugging!turning off:\cr
-1&^^:\>{-1}: Turn on limited debugging for \FWEAVE. 
 ^^:debugging!turning on!limited:\cr
-2&^^:\>{-2}: Turn on full verbose debugging for \FWEAVE. ^^:debugging!turning
 on!verbose:\cr 
-A&^^:\={-a}{-A}: Turn on translations to \&{ASCII}.  (On \&{ASCII} machines,
 translations to the internal \&{ASCII} representation are redundant, so are
 turned off by default.  This flag is used for debugging.  On non-ASCII
 machines, the translations are done regardless of the setting of this
 flag.) ^^:ASCII!turning on translations to:\cr 
-b &^^{\>{-b}} Number \&{do} and \&{if}~blocks in woven \Fortran\ and \Ratfor\
	output.  This is helpful when the blocks are highly nested and/or long.
	The form of this numbering is defined by the \.{fwebmac}
	macro \.{\\Wblock}, which by default prints as `\hbox{\Wblock{99}}'.
	^^:\CS{Wblock}: ^^{block numbers}\cr
\lstar -c&^^:\>{-c}: Set the global language to~\C. \It{(Will be overridden
	by a language command in limbo.)} ^^:language!global!C:\cr
-c++&^^:\>{-c++}: Set the global language to~\Cpp.
	^^:language!global!\Cpp:\cr 
-D\It{[letters]}&^^:\={-d}{-D}: Display information about reserved words of the
	current (command-line) language (beginning with \It{letters} if
	present).   
	For example, to see all the reserved words of~C, say ``\.{ftangle
	-c -D}''.
	^^:reserved words!displaying:\cr
-d\It{[nnnnn]}&^^:\>{-d}: In \Fortran--77, this tells \TANGLE\ to convert
	unnumbered `\&{do}\dots\&{enddo}' constructions to numbered ones of
	the form `\&{do} 
	{10000} \dots\ {10000} \&{continue}'. The constructions are numbered
	uniquely, without regard for subroutine boundaries. By default, the
	numbering starts with a large number such as~90000. If you wish to
	change 
	that starting number, say `-d\It{nnnnn}', where \It{nnnnn} is an
	integer 
	number sufficiently less than~99999. Any statement numbers that you use
	yourself should be less than that starting number.  (This feature
	is a kludge and is slow; use \Ratfor\ instead.)
	^^:\<{do}!numbering:\cr
}
\vfill\Eject
\clo{
-E$c$&^^:\={-e}{-E}: Change the delimiter of a file-name extension from the
	default~'\..' to~'$c$'.  This option is included because on some
	(weird) systems the period is used as a directory delimiter.
	^^:extensions!file-name!changing delimiter for:\cr
-e&^^:\>{-c}: Turn on automatic file-name completion.  ^^:file
name!automatic completion of:
If any file name contains a period, then it is assumed that this is the
complete name of the 
file to be opened.  If it does not contain a period, then trial names are 
constructed by appending in turn each extension from the relevant
style-file extension list:  one of \.{ext.web}, \.{ext.change},
\.{ext.hweb}, or  
\.{ext.hchange}.  The first trial name that matches a file in the user's
directory is opened.  For example, if one says in the style file
``\.{ext.hweb = "hweb\ hw"}'' and uses an include line of the form ``\.{@i\
my\_includes}'', the system will search for the include files
\.{my\_includes.hweb} and \.{my\_includes.hw}, using the first one it
finds.\cr 
-f&^^:\>{-f}: Turn off the module reference subscripts for all identifiers.
^^:module!references!turning off:\cr
\lstar -h&^^:\>{-h}: Get help from the command line. \It{(Not implemented
	yet; just refers the user elsewhere and quits.)} ^^:help!command
	line:\cr  
-i&^^:\>{-i}: This option is intended to help cut down on the volume 
	of woven output. It tells \FWEAVE\ to read include files named by the
	\atcmd{I} command, but to not print their contents. (Include files
	named by~\atcmd{i} will always be processed fully, regardless of
	any command-line 
	options.) This command will only work properly if the included text
	is a 
	complete module, or has no new-module commands in it at all.
	^^:file!including!not printing:\cr
-i!&^^:\>{-i"!}: Tells \FWEAVE\ to not even read include files named by
	the \atcmd{I}~command.\cr 
-I&^^:\={-i}{-I}: Append a directory to the list of
	directories to be search for include files. (That list begins with
	the contents of the environment variable \\{FWEB\_INCLUDES} 
	^^:\>{FWEB\UL INCLUDES}: 
	^^:environment variables!\>{FWEB}!\>{FWEB\UL INCLUDES}: 
	if that 	is defined.)  The argument of this option can also be a
	colon-delimited list of directories.\cr
}
\vfill\Eject
\clo{
-k\It{[letters]}&^^:\>{-k}: This option turns off the comment lines
	generated by \.{FTANGLE} during 
	\Ratfor\ statement translation. The `\.k' must be followed by a list of
	single lower-case characters (no quotes are required). If any of those
	characters is an asterisk, or if the list is empty,
	then all comment lines are suppressed.
	Otherwise, the characters serve as abbreviations for which \Ratfor\
	keyword the comment should be suppressed, as follows:
$$\def\htop#1{\vtop{\halign{\tt##\hfil&\ ---\ \&{##}\hfil\cr#1}}}
\htop{
b&break\cr
c&case\cr
t&default\cr
d&do\cr
f&for\cr
i&if\cr}
\qquad\qquad
\htop{
n&next\cr
p&repeat, until\cr
r&return\cr
s&switch\cr
h&where\cr
w&while\cr
}$$
For example, `\.{-kbn}' will suppress comments about the \&{break} and
\&{next} statements. ^^:Ratfor\actual\RATFOR!commands!deleting:\cr
-K\It{[letters]}&^^:\={-k}{-K}: As above, except that the list of
	abbreviations specifies which comments to include, rather than to
	suppress.\cr 
-l\It{[mmmm[:nnnn]]}&^^:\>{-l}: Echo the input line that the input driver has
	constructed, between lines~\It{mmmm} and~\It{nnnn}. Useful for
	debugging (especially for \FWEB\ itself), but 
	rather slow. The command 
	`\.{-l}\It{nnnnn}' echos all lines beginning with line~\It{nnnnn};
	if you just say~`\.{-l}', the echo starts with the first line.
	^^:debugging!echoing input lines:\cr
\lstar -L\It{l}&^^:\={-l}{-L{\it l}}: Select language~$l$, where $l \in
\{\.c,\.n,\.r,\.x\}$.\cr 
\lstar -m\It{id[=text]}&^^:\>{-m}: The construction `\.{-m}\It{string}', where
	\It{string} does not begin 
	with~`\.4', allows one to define \WEB\ macros from the command line. To
	define the lower-case macro name `\.{test}' with null replacement
	text, say 
	`\.{-mtest}'. To give \.{test} a value, say `\.{-mtest=5}'. (No
	spaces are 
	allowed before or after the equals sign.) This is
	equivalent to saying at the beginning of the definition section of the
	first module \atcmd{m test 5}. (The equals sign in lieu of a space
	between 
	macro name and replacement text is allowed \It{only in definitions made
	from 
	the command line}, but allows you to avoid having to type quotes to 
	ensure 
	that the space is counted as part of the definition. For example,
	although 
	allowable, it's more cumbersome to type `\.{-m"test 5"}'.)
	Under~VMS, if 
	your macro name is upper case (a common convention), you must
	enclose the 
	definition in quotes, otherwise the name will be turned into lower case
	by~VMS. ^^:language!selecting:\cr
-m4&^^:\>{-m4}: Tells \WEAVE\ to understand the \.{m4} built-in commands.
	Also makes the 
	output extension~`\.{m4}' instead of~`\.{rat}', or~`\.{n4}' instead
	of~`\.{for}'. ^^:\>{m4}!understanding commands of:\cr 
-m;&^^:\>{-m;}: Tells \WEAVE\ to automatically append a
	pseudo-semicolon to 
	the end of \WEB\ macro definitions. \It{(Not recommended; insert
	pseudo-semis explicitly where necessary.)}
^^:pseudo-!semicolon!appending automatically:\cr       
}
\vfill\Eject
\clo{
\lstar -n&^^:\>{-n}: Set the global language to \Fortran-77.
	^^:language!global!Fortran--77\actual\FORTRAN--77:\cr  
-n9&^^:\>{-n9}: Set the global language to \Fortran--90.
	^^:language!global!Fortran--90\actual\FORTRAN--90:\cr 
-n;&^^:\>{-n;}: For \Fortran--77, supply semicolons automatically.  (This
	is done automatically by default.)
	^^:semicolons!automatic!Fortran\actual\FORTRAN:\cr 
-nb &^^:\>{-nb}: Number \&{do} and \&{if}~blocks in woven \Fortran\
	output.  This is helpful when the blocks are highly nested and/or long.
	The form of this numbering is defined by the \.{fwebmac}
	macro \.{\\Wblock}, which by default prints as `\Wblock{99}'.
	^^{\CS{Wblock}} ^^:block numbers!\Fortran:\cr
\lstar -np&^^:\>{-np}:  Print semicolons in woven \Fortran\ output.  (Don't
	confuse with `\.{-n;}', described above.) ^^:semicolons!printing:\cr
-n\BS&^^:\>{-n\BS}:  Use free-form syntax for \Fortran--90; continue
	lines with a backslash. ^^:syntax!free-form!continuing with
	backslash:\cr 
-n\amp&^^:\>{-n\amp}:  As above, but continue lines with the
	ampersand. ^^:syntax!free-form!continuing with ampersand:\cr 
-n/&^^:\>{-n/}: In \Fortran, make '\.{//}'~denote the start of
	a short comment instead of  concatenation.  (One can always
	use~'\.{\\/}' ^^{\CS{/}} for concatenation.)
	^^:comment!short!recognizing in 
	\FORTRAN:\cr 
-n!&^^:\>{-n"!}: In \Fortran, make
	`\.!'~denote the start of a short comment instead of the logical
	\.{NOT}.\cr 
\medalign
-o&^^:\>{-o}: Turn off \FWEAVE's mechanisms for overloading operators.
	^^:operator!overloading!turning off:\cr
\lstar -P\It{[letter]}&^^:\={-p}{-P}:  Inform \FWEAVE\ about which processor,
	\TeX\ or \LaTeX, will be used to process the \.{.tex} file.  The
	default is~`\.{-PT}' (\TeX); to select \LaTeX, say~`\.{-PL}'.  The
	empty command~`\hbox{\.{-P}}' is equivalent to~`\.{-PT}'.
	^^:\TeX\ processor, selecting:\cr
-p\It{cmd} &^^:\>{-p}: This absorbs a style-file command, which will be
	processed just before the local style file is read.  This option is
	useful in the initialization file \.{.fweb}; style-file options
	common to all jobs can be put there, leaving only things that
	customize individual runs to the local style file.\cr
-q&^^:\>{-q}: Turn off translation of \Ratfor\ commands into \Fortran.
	(This command is no longer supported.)\cr
\medalign
\lstar -r&^^:\>{-r}: Set the global language to~\Ratfor--77.
	^^:language!global!Ratfor--77\actual\RATFOR--77:\cr 
-r9&^^:\>{-r9}:  Set the global language to~\Ratfor--90.
	^^:language!global!Ratfor--90\actual\RATFOR--90:\cr  
-rb &^^:\>{-rb}: Number \&{do} and \&{if}~blocks in woven \Ratfor\
	output.  This is helpful when the blocks are highly nested and/or long.
	The form of this numbering is defined by the \.{fwebmac}
	macro \.{\\Wblock}, which by default prints as `\Wblock{99}'.
	^^{\CS{Wblock}} ^^:block numbers!\Ratfor:\cr
-rg\It{params}&^^:\>{-g}: This option sets the parameters for the decision
	between the computed 
	\&{goto} and \&{if} statements for expanding the \Ratfor\
	\&{switch}. See the 
	discussion of \Ratfor\ for a detailed discussion of this command.\cr
\lstar -r;&^^:\>{-;}: For \Ratfor, make the input driver
	supply the semicolons automatically and use the ``obviously continued''
	syntax. (It's recommended that  this option not be used. When
	the programmer supplies the semicolons,  \Ratfor\ looks quite
	close to~\C.) ^^:semicolons!automatic!Ratfor\actual\RATFOR:\cr
-r/&^^:\>{-n/}: In \Ratfor, make '\.{//}'~denote the start of
	a short comment instead of  concatenation.  (One can always
	use~'\.{\\/}' for concatenation.)  ^^:comment!short!recognizing in
	\RATFOR:\cr
-r!&^^:\>{-r"!}: In \Ratfor, make `\.!'~denote the start of a short comment
	instead of the logical \.{NOT}. \cr 
}
\vfill\Eject
\clo{
\lstar -s&^^:\>{-s}: Print statistics about memory usage at the end of the
	run. ^^:statistics:\cr 
\lstar -sm\It{[nnn]}&^^:\>{-sm}: As above, but also print each dynamic memory
	allocation as it 
	is made. By default, only allocations $\ge 10,000$~bytes are shown.
	However, if you say ``\.{-sm\It{nnn}}'', then allocations
	$\ge$~\It{nnn}~bytes are 
	displayed. (On personal computers, this command also displays some
	indication of how much memory is available at the beginning and end
	of the 	run.) ^^:memory, dynamic allocation of!statistics for:\cr 
\lstar -t\It{ln[\{\dots\}]}&^^:\>{-t}:  Truncate identifiers of language~$l$
	to length~$n$.  If braces are present, the dots signify a list of
	forbidden characters that are removed from the identifier before
	truncation.  (For example, `\.{-tn6\{\_\}}' removes any underscores,
	then truncates the result to 6~characters.)
	If this process results in non-unique identifiers, these will be
	listed.\cr 
\lstar -u\It{id}&^^:\>{-u}: This undefine command is the inverse of
  `\.{-m}'. Saying 
  `\.{-u\It{macroname}}' undefines a macro name either predefined by \WEB\ or
  defined earlier on the command line. Use this command with discretion. Don't
  undefine built-in macros such as \.{\_IF} since other things may also
  stop working because they use that built-in macro internally.
	^^:macro!outer!undefining:\cr
-v&^^:\>{-v}: Tells \FTANGLE\ to make all comments verbatim; that is,
	retain them all in the output.
	^^:comment!verbatim!making all:\cr
-W\It{letters}&Flag-setting commands that apply only to \FWEAVE.  Here
	\It{letters} may be one or more of the following:
	\clo{
	[&^^:\={-w[}{-W[}: Turn on special processing of bracketed array
		indices.\cr 
	f&^^:\={-wf}{-Wf}: Don't print format statements (\.{@f}) in woven
		output.\cr
	l&^^:\={-wl}{-Wl}: As above, but for limbo statements (\.{@l}).\cr
	m&^^:\={-wm}{-Wm}: As above, but for macro definitions (\.{@m}).\cr
	v&^^:\={-wv}{-Wv}: As above, but for operator overloading 
		(\.{@v}).\cr 	
	w&^^:\={-ww}{-Ww}: As above, but for identifier overloading
		(\.{@W}).\cr
	}\cr
\lstar -w\It{[file\_name]}&^^:\>{-w}: With no argument,
	do not print ``\.{\\input
	fwebmac.sty}'' as the first line of the \.{.tex} output file. 
	(This may be useful if you have some other macro package that needs for
	some tricky reason to be loaded before \.{fwebmac}.)  With an
	argument, print instead ``\.{\\input \It{file}\_\It{name}}''.
	^^:\>{fwebmac}!\>{.sty}!not printing:\cr
}
\vfill\Eject
\clo{
\lstar -x\It{[letters]}&^^:\>{-x}: Reduce or eliminate printed
  cross-reference information.  The optional letters refer to which piece of
  information should \It{not} be
  printed; they can be one or more of~'\.c', 
  '\.i', '\.m', or~'\.*', referring respectively to the table of contents,
  index, module list, or all cross-reference information.  The 
  command~`\.{-xi}' means ``do not print the index, but print the module list
  and   
  table of contents''. The command~`\hbox{\.{-xim}}' means ``print only the
  table of 
  contents, as does~`\.{-Xc}' (see the next option) or even~\hbox{`\.{--xc}'}.
  The command~`\.{-x}' is 
  equivalent to~`\.{-x*}', which means ``print nothing''.
	^^:cross-references!suppressing:
	^^:index!suppressing:\cr
	^^:module list!suppressing:\cr
	^^:table of contents!suppressing:
\lstar -X\It{[letters]}&^^:\={-x}{-X}: Print selected cross-reference
  information; equivalent to~`\.{--x}'.  To suppress printing of the index
  and module list, but retain the table of contents, say~`\.{-Xc}'.  The
  default is `\.{-X*}', which means print everything.
	^^:index!printing:\cr
\lstar -y\It{a[a]nnnn}&^^:\>{-y}: Allocate dynamic memory.
  The format is \.{-y}\It{aa}$nnnnn$, where
  \It{aa}~stands for a one- or two-character abbreviation for the relevant
  array and $nnnnn$~is the number of elements in the array. See the section
  below on dynamic memory allocation for more details.
	^^:memory, dynamic allocation of!syntax:\cr
-Z\It{[letters]}&^^:\={-z}{-Z}: Print default value of style-file parameters.
  If \It{letters} are absent, information about all parameters is displayed.
  If \It{letters} are present, information about only parameters beginning
  with \It{letters} is displayed.  
	^^:style file!parameters!default values of:\cr
-z\It{[name]}&^^:\>{-z}: Specify a new name for the style file, as in
  \.{-z\It{newstyle}}. (The default name is \.{fweb.sty}.) If no name is
  given, the null file is assumed. ^^:style file!new name for:\cr
\lstar -.&^^:\>{-.}:  In \Fortran\ or \Ratfor, do not recognize ``dot
	constants'' ^^{constant!dot}
	such as `\.{.eq.}'.  (Use the modern \WEB\ alternatives
	such as `\.{==}'.) \cr
\lstar -\BS&^^:\>{-\BS}: Explicitly escape continued strings.  Without this
	option, continued strings must begin in the first column of the
	next line.  With this option, the continuation line may begin with
	white space followed by an escape character; the string continues
	after the escape character.  In~C, the escape character is the
	backslash; in \Fortran\ or \Ratfor, it is selected by~`\.{-n\&}'
	or~`\.{-n\\}'. ^^:strings!continuing!with explicit escape:\cr 
\lstar -(&Continue parenthesized strings (arguments of certain built-in
	commands) with backslashes. ^^:strings!parenthesized!continuing:\cr
\lstar -:\It{nnnnn}&^^:\>{-":}: The command `\.{-:}\It{nnnnn} sets the
	starting automatic statement number for \Fortran\ and \Ratfor.
	^^:statement!number!setting:\cr
->\It{[l=][name]}&^^:\>{->}: Redirect output. The command~`\.{->}' (or its
	synonym~`\.{-=}') 
	with no argument redirects output to the terminal. The most general
	form is 
	`\.{->\It{l}=\It{name}}', which redirects output for language~\It{l}
	to the file \It{name}. See the section on output redirection for
	more details. ^^:output!redirection:\cr 
-=\It{[l=][name]}&^^:\>{-=}: Redirect output; same as~`\.{->}'. Useful under
	\Unix, because '\.>'~has special significance to the shell.\cr 
\lstar -\#&^^:\>{-\PM}: Turn off commands about line numbers and module
names in tangled output. ^^:line!numbers!turning off:\cr
\lstar -+&^^:\>{-+}: In \Fortran\ or \Ratfor, don't allow the compound
	assignment operators `\.{++}', `\.{--}', `\.{+=}', `\.{-=}',
	`\.{*=}', or 
	`\.{/=}'. ^^:operators!compound assignment!not recognizing:\cr 
-/&^^:{\>{-/}}: In both \Fortran\ and \Ratfor, make `\.{//}'~denote the
	start of a short comment instead of  concatenation.  (One can
	always use~'\.{\\/}' ^^{\CS{/}} for concatenation.) \cr
-!&^^:{\>{-"!}}: In both \Fortran\ and \Ratfor, make 
	`\.!'~denote the start of a short comment instead of the logical
	\.{NOT}.\cr 
}
^^)options!command-line)

\dsubsection Initialization file ({\tt .fweb} or {\tt fweb.ini}).
^^(file!initialization( 

Commonly used options can be placed into an initialization file instead of
repeated each time on the command line. The name of this file is determined
as follows.  On systems that support environment variables (^{logical names}
under VMS), if the
environment variable \.{FWEB\_INI} 
^^:\>{FWEB\UL INI}: ^^:environment variables!\>{FWEB}!\>{FWEB\UL INI}:
is defined, then that is the name of the ini file.  As examples,

{\codemode
setenv FWEB_INI .fweb \qquad{\it (\Unix)}
define FWEB_INI .fweb \qquad{\it (VMS)}
}
\noindent This should just be the raw file name, such as \.{.fweb}; no path
should be specified, since
the initialization file must be placed into the
user's \It{home directory} (\It{not} the current one). 
If \.{FWEB\_INI} is not defined, then if the operating system allows a file
name to begin with a period the name is
``\.{.fweb}''.  ^^:\>{.fweb}: (It begins with a dot so it will be invisible
by default on \Unix\ systems.) Otherwise, as on the IBM-PC, the name is
instead ``\.{fweb.ini}''. ^^:\>{fweb.ini}:
Any argument that
can be placed on the command line 
can be placed into \.{.fweb}. (Presently, they cannot be continued across
newlines.) 
For options that on the command line would begin with a hyphen, one can
either use the hyphen or, alternatively, a plus sign. Ini options beginning
with a plus sign are processed \It{before} the command-line arguments; ini
options beginning with a hyphen are processed \It{after} the command-line
arguments. Entries beginning with anything other than a hypen or plus sign
are interpreted as file names, and are processed after any file names found
on the command line.  Usually one uses the plus sign for ini file options,
so that one can override them on the command line if desired.

Comments may be used in the ini file. ^^:comment!in initialization file:
They follow the same format as those
for \TeX: namely, anything beginning with a per~cent sign is ignored to the
end of the line.

Thus, a sample initialization file is

{\codemode
% Sample FWEB initialization file.
+PL % LaTeX will be used.
+v % Retain all comments in tangled output.
+n9 % Assume Fortran--90,
+n\\ %   with free-form syntax.
}

^^)file!initialization)

\dsection ADVANCED FEATURES.[15.4] ^^(features!advanced(

Knowledge of the following features is not necessary for simple uses of the
\WEB\ system.  However, they can be very useful in unusual applications.
It is particularly helpful to learn how to use the style file.

\ddsubsection Input and output redirection. ^^(redirection(
^^[input!redirection]^^[output!redirection] 

As we have explained, the \FWEB\ processors read their input by default
from a file with extension \.{.web}.
\FWEAVE's \TeX\ output goes by default into a file with
extension \.{.tex}; \FTANGLE's compilable output goes by default into
\.{.sty}, \.{.c}, \.{.rat}, or \.{.for} files. (Under \Unix, the latter two
are~\.{.r} 
and~\.{.f}.) Occasionally, one may wish to override these defaults. It is
most useful to redirect the output.  This can be done with the command-line
option~`\.{->}' or its synonym~`\.{-=}'. The bare command~`\.{->}'
redirects all output to the terminal. The command
``\hbox{\.{->}\It{file\_name}}'' redirects all output to the file
\It{file\_name}.
(For \FTANGLE, this kind of redirection is not very useful if you're
working with more than one 
language.) The command ``\hbox{\.{->}$l$\.=\It{file\_name}}'' redirects output
intended only for the file associated with
language~$l$, where $l$~is one of~\.x, \.c, \.r, or~\.n. (Use~\.n if you're
working with \Ratfor; the symbol refers to the output file that is being
created, not the language from which things are being produced.) If
\It{file\_name} contains the symbol~'\.\#', that 
symbol is expanded into the name of the web file. Thus, for example, if you
say ``\hbox{\.{ftangle test ->\#.out}}'', all output is redirected into the
file \.{test.out}. 

One should not confuse \FWEAVE's redirection with the redirection provided by
\Unix\ shells. The default \FWEB\ processors cannot be used as \Unix\ filters:
by default they neither take their input from the standard input nor write
it to the standard output; they take it from, and write it to, files.
(Information and error messages are always written to the standard output.)
The
\FWEB\ command~`\.{->}' makes \FWEB\ write all output to the standard output;
that output could then be redirected again by the \Unix\ shell. Thus, the
\Unix\ command ``\.{ftangle test -= >test.out}'' puts all output, both
information and compilable code, into \.{test.out}. If you didn't use the
`\.{-=}'~option, you would just get the information messages in \.{test.out}.
Incidently, it should now be clear why the command~`\.{-=}' was introduced as
a synonym for~`\.{->}'. \Unix\ would interpret the~'\.>' as a redirection
command to the shell, and it's cumbersome to type~`\.{-\\>}' when you're in a
hurry.

Input redirection is also possible; just replace the web file name by
``\.{stdin}'' ^^{\>{stdin}}
or, equivalently, a single hyphen. Thus, the command
``\.{ftangle stdin}'' or equivalently ``\.{ftangle -}'' reads from the
standard  
input (usually the terminal). (The analogous command for \FWEAVE\ doesn't
work in a reasonable way, since \FWEAVE\ makes two passes over the input
file.) Thus, you can force \FTANGLE\ to be a \Unix\ filter by saying
``\.{ftangle stdin -=}''. For example, if you say ``\.{ftangle <test.in
stdin -= >test.out}'', input will be taken from \.{test.in} and written to
\.{test.out} (along with the information messages). Note that ``\.{ftangle
<test.in stdin}'' is equivalent to just ``\.{ftangle test.in}''; however,
``\.{ftangle test.in -= >test.out}'' is not quite equivalent to ``\.{ftangle
test.in >test.out}''. The former puts everything into \.{test.out}; the
latter just puts the information messages into \.{test.out}.
^^)redirection)

\dsubsection Customizing \FWEB: The style file {\tt fweb.sty}.[15.2.4]
^^(customization( ^^[style file]

It is possible to customize various aspects of \FWEB's behavior.
The original motivation was to provide some control over the appearance of
the index; the same mechanism can also be used to change the definitions of
many of \FWEB's '\.@'~commands and to customize other facets of \FWEB's
behavior.  (Customizing the production rules is not presently implemented,
but may be in the future.)

\parinsert{3}{4}{0.5}
One can customize behavior with the style file {\ssbf fweb.sty}.

The solution that
has been adopted follows that for the utility program
\.{makeindex}\cite{makeindex}: ^^{\>{makeindex}}
namely, a \It{style file} can be supplied. If present, the style file
is read in after the command line is parsed.  This file is located in the
directory specified by the environment variable
\.{FWEB\_STYLE\_DIR}, ^^:\>{FWEB\UL STYLE\UL DIR}:
^^:environment variables!\>{FWEB}!\>{FWEB\UL STYLE}:
if that is defined.  Otherwise, it is assumed that the style
file is in the current directory. The default name of the style
file is \.{fweb.sty}; ^^:\>{fweb.sty}:
that can be overridden by using the command-line option~`\.{-z}'. ^^{\>{-z}}
(If you say ``\.{-z}'' with no argument, the style file is
null; specify an alternate name by saying ``\.{-z\It{name}}''.)
Its contents consists of a
sequence of keywords and keyword arguments, in essentially free-form
format.  The keywords and arguments are separated by white space, and/or
optionally an equals sign.  Also, periods in keywords are equivalent to
underscores.  Thus, the following two lines are equivalent:

{\codemode
lethead_flag 1
lethead.flag = 1
}
\noindent (The form with the period is preferred; the intent is to emulate
structure references in~\C.)
The arguments can be either single characters (surrounded by single
quotes), character strings (surrounded by double quotes), boolean (0~for
\\{NO}, 1~for \\{YES}), or integers
(optionally followed by a trailing \.L for \&{long}). As in~C, characters
can be escaped with a backslash. Thus, for example, to include a double
quote and a newline inside a string, say \.{"\dots\\"\dots\\n\dots"}.

Comments may be included in the style file. ^^:comment!in style file:
They follow the \TeX\ format:
everything from a per~cent character to the end of line is ignored.

At present, there can be just one style file. No \.{include} command is
allowed within a style file. (Someday these restrictions may be removed.)

In the following discussion, the style-file vocabulary 
^^[style file!vocabulary]
is presented in functional groups.  For an alphabetical listing of all of
the vocabulary entries, see the index entry ``style file, vocabulary''.
Also, to save space, the actual list of keywords associated with each group
is not given here, but is rather presented in Appendix~M.  Here, we content
ourselves with a summary of the available features and some examples of
their use. 

\dsubsubsection Customizing the index, {etc.}.

First there are keywords related to customizing the index, module list, and
miscellaneous features that are
recognized in the style file. (In conjunction with these keywords, you
should also study the \.{\\Wcon} macro in \.{fwebmac.web}.)
^^[index!customizing] ^^{\CS{Wcon}} ^^{\>{fwebmac}!\>{.web}}
Note that during its processing \FWEB\ uses several temporary files to
accumulate the index, list of modules, and the table of contents.  By
default, these are called \.{INDEX.tex}, ^^:\>{INDEX.tex}:
\.{MODULES.tex}, ^^:\>{MODULES.tex}:
and \.{CONTENTS.tex}.  ^^:\>{CONTENTS.tex}:
When working with more than 
one file at a time, it is desirable to change these names to include the
file name.  This can be done by incorporating the
character~`\.{\#}' into the style-file field; this character is
translated into the root name of the web file.  For example, a typical
style file might contain the entries

{\codemode
index.tex "#.ndx"
modules.tex "#.mds"
contents.tex "#.cts"
}

%\input index.stl

As an example, here is how one might beautify \FWEAVE's index (see
Appendix~M, ``Customizing \FWEAVE's index''):

{\codemode
% --- SAMPLE STYLE FILE fweb.sty ---
\Par
limbo "\\\\input fweb" % Input fweb.tex automatically just after fwebmac.sty.
\Par
% If the source file is test.web, make the name of the index file \.{test.ndx}.
index.tex "#.ndx"
\Par
% Separate index entries by \\letter\{...\}. See fweb.tex for \\letter.
lethead.prefix "\\\\letter\{" 
lethead.suffix "\}\\n"
lethead.flag -1 % Use lower-case letters.
}
\noindent The file \.{fweb.tex} contains \TeX\ macros used for producing
the woven output of the \FWEB\ sources themselves.  In it, one finds the
definition of \.{\\letter}, which in part looks like 

{\codemode
\\def\\letter#1\{\\hbox\{\dots\\kern2em--- \{\\tt #1\} ---\}\\smallskip\}
}
\noindent With this definition, each index entry will be preceded by a line
that contains a construction such as \hbox{``--- {\tt a} ---''} to denote the
start of each new letter group.


For further information about customizing the module list and table of
contents, see App.~M, ``Customizing
\FWEAVE's module list'' and ``Customizing \FWEAVE's table of contents.''

%\input modules.stl
%\input contents.stl

\FWEB\ can attach cross-reference information as subscripts to various
entities such as function names.  \FWEB\ will do this by default for some
entities, but not for others.  To change the defaults, see App.~M,
``Customizing cross-reference subscripts.''

%\input subs.stl

When \FWEAVE\ writes the \.{.tex} file, it emits the names of
various macros that are used by the \FWEB's macro package \.{fwebmac.sty}.  
In some cases it is desirable to have some control over these names without
recompiling \FWEB.  For further information, see App.~M, ``Overriding or
completing definitions in \.{fwebmac.sty}.''

%\input formats.stl

There are various miscellaneous customization commands for \FWEAVE.  One
important one is the \.{limbo} command, which specifies \TeX\ material that
\FWEAVE\ should print at the beginning of the limbo section.  For example,

{\codemode
limbo "\\input fweb"
}
\noindent writes the line ``\.{\\\\input fweb}'' somewhere soon after the
first line of the output file, which is generally ``\.{\\\\input
fwebmac.sty}''.  This provides a way of including a user's macro file in
addition to the default one of \FWEB.  For more information, see App.~M,
``Miscellaneous customization commands for \FWEAVE.''

%\input wmisc.stl

A variety of parameters are useful only for \FTANGLE.  These include the
\.{cdir\_start} commands, which specify default text that should be output
at the beginning of every compiler directive (initiated by~\atcmd{?}).
Also, one can specify the extension for the output file for each language
with the \.{suffix} command.  For more information, see App.~M,
``Customizations for \FTANGLE.''

%\input t.stl

For a few miscellaneous commands, see App.~M, ``Miscellaneous
customizations for both \FTANGLE\ and \FWEAVE.  

%\input wtmisc.stl


\dsubsubsection Automatic file name completion. ^^(file name!completion(

When the `\.{-e}'~option is in effect, ^^:\>{-e}:
file names that contain no period
will be completed automatically by using extensions from the 
style-file entries described in App.~M, ``Automatic file-name completion.''
The entries such as \.{ext.web} are strings that 
contain a blank-delimited list of extensions. Complete file names are
created by applying each of these extensions in turn to the original name;
the first full name that matches a directory entry is used.  Thus, if one
says ``\.{ext.change = "ch chng"}'', then if the `\.{-e}'~option is in
effect the command line ``\.{ftangle test test}'' means to tangle
\.{test.web} with the change file \.{test.ch} or, if that does not exist,
with the change file \.{test.chng} if that exists.

%\input auto.stl

^^)file name!completion)

\ddsubsubsection Custom colors. ^^(color(

\parinserto{3}{4}{0.33}
``Color is obviously a frill.  Have fun...''

\FWEB\ supports a \It{restricted, experimental, and incomplete}
color enhancement mode. Color output is 
not considered to be essential, since \FWEB\ is not interactive and usually
prints only a small amount of information to the terminal.  Nevertheless,
color can be usefully used for emphasis---e.g., for error messages, file
names, etc.---and those who have spent
considerable amounts of money on a color monitor like to feel that they're
getting their money's worth.  Unfortunately, color manipulations are not
fully standardized.  The X~Terminal System standardizes one mode of
manipulating color, and someday there may be an X~version of \FWEB.
Meanwhile, \FWEB\ can be taught to translate color commands into \.{VT100}
escape sequences, so various highlighting modes such as underlining, double
intensity, etc., can be used with standard terminal emulators such as
\.{xterm}. 

Here's how it works.  The information output by \FWEB\ has been classified
into various types; each type can be assigned a different color.  For
example, referring to the list below,  error messages have the type
\.{color.error}.  Each type has a default color that can be overridden
in the style file, as in 

{\codemode
color.error = "red"
}
\noindent Ultimately, these colors will
correspond to R--G--B triplets.  However, in this restricted implementation
they are mapped to
\.{VT100} escape sequences.  There are also defaults for these, or they can
be set in the style file, as in

{\codemode
color.red = "md mr"
}
\noindent (Note the space separating multiple escape sequences.)
The abbreviations such as~``\.{md}'' for the escape sequences are those
standardized 
by \.{termcap} files; in \Unix, see the man page for \.{termcap}, or in
\.{emacs} see the \.{termcap} menu item.  Thus, the previous example means
that red information fields will be displayed as double intensity reverse
video. 

Whether any kind of color manipulation is operative is specified by the
variable \.{color.mode}.  When \.{color.mode = 0}, no color manipulations
are done. When \.{color.mode = 1}, a ``bilevel'', essentially
dual-intensity palette is selected, with the default sequences as below.
When \.{color.mode = 2}, true color is supposed to be selected; however, at
present, that also corresponds to a particular mapping between colors and
escape sequences.  Experiment to see what happens.

Color is obviously a frill.  Have fun playing with it, but don't forget to
do some real work too.  For the list of available commands, see App.~M,
``Colors''. 

%\input colors.stl

^^)color)
\par
\ddsubsubsection Customizing control codes.

Now we describe how to customize \FWEB's control codes. \It{This feature is
still experimental, and is recommended for advanced users only.} (No,
cancel that; \It{it's not recommended at all}.) Generally, the default
codes are 
adequate. However, occasionally one might want to change the code that maps
to a particular operation.  The format is the keyword listed below,
followed by a (double-quoted) character string containing all the symbols
that you wish to map onto the operation associated with the keyword. For
example, if you want to allow the use of any of~\atcmd{a}, \atcmd{A},
or~\atcmd{j} to denote the start of the unnamed module, you would use a
style file entry

{\codemode
begin_code "aAj"
}

\noindent In the above, replace the string~\.{"aAj"} by~\.{"j"} if you want
to use only~`\.{@j}'.

There may be no
overlaps---i.e, one can't map the same character onto two different
operations. Also, because of design decisions built into the original
\WEB, some commands with different meanings are all mapped onto the same
fundamental operation, such as the commands~\atcmd{\ } and~\atcmd{*}. At
present, such commands cannot be remapped.  

For more information, see App.~M, ``Customizing \FWEB's control codes.''
^^[control codes!customizing]

%\input ccodes.stl

^^)customization)

\ddsubsection Dynamic memory allocation. ^^(memory, dynamic allocation of(
^^[allocation, dynamic memory]

\FWEB's internal buffers and arrays are allocated dynamically (at run time,
rather than at compile time). Although default lengths are built into
\FWEB\ and will be adequate for most applications (in particular, for
running the \FWEB\ processors on themselves and each other), the facility
does exists 
to change those. (One might need to enlarge certain arrays for an unusually
large job, or one might need to shrink things to make them fit on a
personal computer.) Dynamic memory allocation is done with the 
command-line option~`\.{-y}'.
^^:\>{-y}:
This is followed by a one- or two-character
abbreviation for the array in question, followed in turn by the number of array
elements (not bytes) to allocate, as in `\.{-yb150000}'.  These
abbreviations are described more fully in Appendix~N.

In general, \It{you probably shouldn't fiddle around with dynamic memory
allocation unless you understand the inner workings of \FWEB\ in
considerable detail}. However, someday one of the processors may complain
that it ran out of memory for one reason or another; then you may wish to
try overriding the default.  Usually the error message will tell you which
abbreviation to use as well as its maximum allowed value.  (Beware: if it's
the macro buffer that overflowed, there's probably something wrong with the
macro, or there's a bug in \FTANGLE.)  Sometimes, however, the message will
simply tell you that it ran out of memory, but it won't deign to advise you
which array to shrink.  In this case, proceed as follows.  First, determine
the default allocations by using the `\.{-y}'~option with no arguments.  (Query
just one option by saying `\.{-y\It{a[a]}}'.)
Alternatively, one can run a very small test code with the
`\.{-s}~option; that reports statistics about the principal buffers at the
end of the run.  (If you want even more information, use the
option~`\.{-sm}' to obtain a detailed accounting of the dynamic memory
allocations as they occur.)  Then, attempt to shrink one or more of the
largest buffers by using the appropriate `\.{-y\It{a[a]nnnnn}}'~option;
refer to Appendix~N. 


After one determines an appropriate set of allocations, one typically puts
the allocation commands into the ini file 
\.{.fweb}, since the same parameters would likely be used for many runs.
^^)memory, dynamic allocation of)

\ddsubsection Debugging. ^^(debugging(

There is no denying that the use of named sections (in this discussion we
explicitly distinguish between modules and sections: modules are the
concatenations of all sections with the same name) significantly helps one
to write structured, readable code. In many cases, one can use a named
section in place of a function call, with all the readability and helpful
cross-reference information of the former but without the overhead of the
latter. Unfortunately, the absence of an explicit function call means
that the job of debugging is somewhat more annoying. One might want to set a
breakpoint at the beginning of the section. Without a function call one must
set a breakpoint at a line number, but this is the line number of the
output file as understood by the compiler, not the \WEB\ file; that line
number may be difficult to determine.

\FWEB\ provides a partial, experimental solution to this
problem. If the user defines \It{from the command line} the \It{breakpoint}
macro \.{\_BP(num,name)},
^^:\>{\UL BP}:
then \FTANGLE\ will insert at the beginning of
every section
that begins with a left brace the expansion of \.{\_BP}, with \\{num}
replace by the section number and \\{name} replaced with the (possibly
truncated) name  (surrounded by quotes) of the module to which the section
belongs. Thus, the user has
complete flexibility to develop his own tracing/breakpointing system. For
example, suppose the C~user issues the command-line option
`\.{-m\_BP(num,name)=trap(num,name);}'. Then each section that begins with a
left brace will begin with a call to the function \\{trap}, which the user
can define as he pleases. He might call another function directly from the
debugger to add or remove a section number from a list of breakpoints, then
arrange to have \\{trap} pause when only the turned-on sections are
encountered.  Exactly how this would work depends in some detail on the
debugger available, but the philosophy itself is quite general. Casual
users of \WEB\ will probably not bother with all this, but for those who
work with large codes this feature may be essential.

C and \Ratfor\ users will have no trouble understanding the restriction to
sections beginning with a left brace; the debugging call needs to be tucked
away inside a compound statement so that it does not inadvertently appear
to be a single statement following a loop and thereby change the program
logic. \Fortran\ users ordinarily do not need to use braces; however, if
they do not, this breakpointing mechanism will not function.  Happily,
straight
\Fortran\ will expand braces just fine---it just ignores them on
output---so things will work consistently in all languages if all sections
that are to be interpreted as ``call-less functions'' are delimited by
braces.

However, C~users will object that one can't always insert an executable
statement immediately after a left brace, because a declaration statement
might be coming up. The solution to this is to replace the left brace
by~\atcmd{\{}. ^^{\>{@\LB}} 
This expands into a left brace, but also prevents the default
insertion. To insert a breakpoint later in such a
section, use the command~\atcmd{b} at the desired place. For example,
^^{\>{@b}}

{\codemode
@ An example of inserting breakpoint commands for debugging.
@<Test@>=
@\{
int i;
\Par
@b
\It{executable code};
@b @% Note that one can insert a breakpoint at more than one place.
\}
}

For an example of section breakpointing functions suitable for use with
C~programs, see the example file \.{breakpt.web}. ^^{\>{breakpt.web}}
It would be easy to
adapt this scheme for \Fortran\ programs as well. That demo also
illustrates the use of the built-in functions \.{\_SECTIONS} and~\.{\_MODULES}.
^^{\>{\UL SECTIONS}} ^^{\>{\UL MODULES}}
^^)debugging)
^^)features!advanced)


\section USAGE TIPS and SUGGESTIONS.[16.2] ^^(usage suggestions(

In this section we collect various tips and suggestions to help one make
full use of the \WEB\ system.  \It{(There's more to come here!)}

\subsection Converting an existing code to {\tt FWEB}.
^^(\>{FWEB}!converting to( 

In summary, to convert an existing code to \FWEB, you should do the
following. (The following simple procedure assumes that you put all the
subroutines into the unnamed module. However, other more elaborate schemes
are possible.)

{\narrower\newfeature

\feature. Place invisible commentary ^^{commentary!invisible}
about the author, version, etc.\ at the beginning of the source file by
bracketing it with~\atcmd{z\dots@x}.  The~\atcmd{z}~must be the first two
characters of the file.

\feature.  Next, set the language by including a command such as~\atcmd{n}.

\feature. Place an \atcmd{a}~command before each program unit (e.g., main
\&{program}, \&{subroutine}, or \&{function}).

\feature. Before each~\atcmd{a}, place an~\atcmd{*} or \atcmd{\ }~command,
followed by \TeX\ documentation about that particular section of code.

\feature. If you have program units longer than about twelve lines, either
make them function calls, if you can afford the overhead and can impart
sufficient information via the function name, or break them up into shorter
fragments by using named modules. Insert the command \atcmd{<\It{Name of
module}@>} in place of the fragment you're replacing, then put that
fragment somewhere else, prefaced by~\atcmd{\ } and \atcmd{<\It{Name of
module}@>=}.

\feature. Make sure your comments are valid \TeX. (You can't have things
like raw underscores or dollar signs in comments, since those cause \TeX\
to take special actions.)

\feature. Beautify and clarify your documentation by using code mode
(enclosing stuff between vertical bars) liberally within your \TeX. 

\feature. After you've seen the woven output, you may need to go back and 
format a few identifiers or section names so that \FWEAVE\ understands them
properly, or you may need to insert some pseudo-semicolons,
pseudo-expressions, or pseudo-colons.
 
\feature. Consider using the built-in macro preprocessor to make your code
more readable---for example, replace raw numerical constants by symbolic
names. 

\feature. If you are a \Fortran\ user,  for ultimate readability
consider converting to \Ratfor. The initial annoyance is getting rid of
column~6 continuations. With the aid of a good editor, this can be done
simply. For example, in \.{EMACS} one can replace the regular expression
[carriage return, five spaces, something not equal to space, tab, or~0]
with [backslash, carriage return, six spaces]:

{\codemode
M-x replace-regexp RET
C-q C-j \.{\ \ \ \ \ }[\^\.\ tab 0]RET
\\\\ C-q C-j \.{\ \ \ \ \ \ }RET
}
\noindent Get rid of the keywords such as \&{then} or \&{end if} in favor
of braces. Change singly-quoted character strings to doubly-quoted ones.

}
^^)\>{FWEB}!converting to)

\subsection Programming tips and other suggestions. ^^(programming tips(

\It{This section will be enlarged in the future!}  Meanwhile, please feel
free to contact \.{krommes@princeton.edu} for help and advice, and to
suggest items to include here.
^^{help!obtaining} 

\newfeature

\feature. Periodically check \.{lyman.pppl.gov:/pub/fweb/READ\_ME} for bug
reports 
^^{bug reports}
^^{programming tips!bug reports}
and other news.

\feature. Most options in \.{.fweb} ^^{programming tips!initialization options}
^^{options!initialization}
should begin with '\.+' so they can be
overridden by command-line options for the job itself.

\feature. Put standard command-line options into \.{.fweb}.  Also put there
standard style parameters---e.g.,

{\codemode
+pindex.tex "#.ndx"
+pmodules.tex "#.mds"
+pcontents.tex "#.cts"
}

\feature. Learn how to use the style file. ^^{programming tips!style file}

\feature. Use the info options `\.{-D}', `\.{-y}', and~`\.{-Z}' 
^^{programming tips!info options}
to find out
about various internal \FWEB\ tables (reserved words, memory allocations,
and style-file parameters).

\feature. Begin all \FWEB\ sources with invisible commentary 
^^{programming tips!invisible commentary}
bracketed by \.{@z\dots @x}.

\feature. Always include an explicit language-setting command in the limbo
section. ^^{programming tips!language setting}

\feature. Keep sections quite short.  ^^{programming tips!section length}
Knuth suggests a dozen lines.  That's
quite hard to achieve sometimes, but almost never should a section be more
than a page long.

\feature. It's easy to  define macros from the command line to expedite
conditional preprocessing. 
^^{programming tips!defining macros from command line} 

\feature. Use the preprocessor construction \.{@\#if 0\dots@\#endif} to
comment out unwanted code.
^^{programming tips!commenting out code}

\feature. For logical operations with the preprocessor, use~`\.{||}',
not~`\.{|}'. 
^^{programming tips!logical operations}

\feature. It's conventional to identify the ends of long preprocessor
constructions as follows:

{\codemode
\If\ A
.
.
\Endif\ // |A|
}

\feature. To debug an errant \WEB\ macro, use the built-in function
\.{\_DUMPDEF}. 
^^{programming tips!debugging macros}

\feature. Use \atcmd{?} for compiler directives (\atcmd{!} is obsolete).
^^{programming tips!compiler directives}
Use the style-file parameters \.{cdir\_start.$l$} to specify 
information that will be written out at the beginning of the line.

\feature. Stick to the standard \FWEB\ commenting style \.{/*\dots */} or
\.{//\dots}.  Don't use alternatives such as \Fortran's column~1
convention; these may not work or may not be supported someday.

\feature. The meta-comment feature \.{@(\dots@)} provides a poor-man's
alignment feature.  But that's not in the spirit of \TeX; learn to use
\.{\\halign} or the \LaTeX\ alternatives.

\feature. In \Fortran, use \.{\#:0} to declare readable alphabetic statement
labels.   
^^{programming tips!alphabetic statement labels}

\feature. When mixing languages, define the language of a module at the highest
possible level---e.g., in the unamed module, not after `\.{@<\dots@>=}'.


^^)programming tips)

^^)usage suggestions)

\section PRESENT STATUS and the FUTURE.

The goal of \FWEB\ v.~1.0 was
to achieve functionality, particularly regarding the macro preprocessor and
\Ratfor. Having done so, it is now time to rework certain parts of the
code in order to achieve portability, optimal speed, and/or eloquence.
This will be done as time permits. Note that the author works with large
codes written with
\FWEB, so there is a powerful incentive to maintain and improve it.
The best way to ensure that \FWEB\ evolves as you would like it is to use
e-mail liberally to make suggestions, report bugs, etc.---send them to
\.{krommes@princeton.edu}.

\comment
\FWEB\ implements almost, but not all features of the new ANSI standard
for~C. ^^{language!C!ANSI standard for} For example, it understands the
names of all of the ANSI library functions, and recognizes the syntax for
function prototyping. However, it does not presently handle trigraphs (a
simple feature to add). Such deficiencies will be removed in future
versions.

Just as the C~language has stabilized with the release of the ANSI
standard, \Cpp~is arising as a significant challenger. Most of the new
features of~\Cpp\ are easy to add to \FWEB, and many already have been; a
few require nontrivial modifications. It is planned that a future release
of the \WEB\ system will fully support~\Cpp. (The command-line
option~\.{-c++} turns on knowledge of~\Cpp.)

Finally, there's \Fortran--90 on the horizon. Partial support for
\Fortran--90 is included in the present release, although this not documented.
(The command-line option~\.{-n9} tells \FWEB\ to recognize \Fortran--90 syntax.)
Although the author isn't sure that one ought to encourage the use of such
a verbose and relatively inelegant language, full support for \Fortran--90
will be provided with the next major release.
\endcomment

\vfill\eject

\section ACKNOWLEDGEMENTS. ^^(acknowledgements(

\parinserto{4}{7}{0.5}
``Many users have
reported bugs and provided suggestions, all of which are greatly
appreciated.''

\.{FWEB} has evolved from the \.{CWEB} code
written by Silvio~Levy ^^{Levy, Silvio} of Princeton University, who
graciously provided the 
author with version~0.5 of the \.{CWEB} source code.  ^^{\>{CWEB}}
Henry Greenside ^^{Greenside, Henry}
greatly fostered the author's initial appreciation of software tools,
particularly \Ratfor.  The author is extremely grateful to Charles
Karney ^^{Karney, Charles} for providing many incisive suggestions about
\.{FWEB} and enormous help 
with all aspects of \TeX\ and computing in general. A number of
beta-testers suffered patiently 
through the initial debugging stage and made many valuable suggestions
(usually not obscene): Cris Barnes, ^^{Barnes, Cris}
John Bowman, ^^{Bowman, John} Charles
Karney, and Chang--Bae Kim. ^^{Kim, Chang--Bae}
(Patience of some of those beta-testers flagged somewhat when
\.{FWEB} stopped working a few days before a major  meeting of the American
Physical Society, but that is
perhaps understandable.) Arnold Kritz ^^{Kritz, Arnold}
generously provided both precious
time and the use of his excellent, super-enhanced IBM-PC system for
developing the original PC~version.  Barbara Kritz ^^{Kritz, Barbara}
made a seminal contribution by locating the key PC~disk on Arnold's desk.
Thorsten Ohl ^^{Ohl, Thorsten}
provided expert, trans-Atlantic
assistance and advice in debugging first the PC~version, then the ASCII
translations necessary for non-ASCII machines. Many  users have
reported bugs and provided suggestions, all of which are greatly appreciated.
Charles Karney and Bart Childs ^^{Childs, Bart}
contributed nice demos of the use of
\Fortran\ \FWEB\ (see \.{adj.web} and \.{series.web}, respectively).  
Bart Childs furnished a variety of insightful remarks about literate
programming that influenced aspects of the design of \FWEB.  Tom McCurdy
and Clarissa Wilson furnished the short pedagogical introduction
\.{Intro.tex} to \WEB\ programming that is included with the \FWEB\ release.

This work was supported by U.S. D.o.E. contract DE--AC02--76--CHO--3073. 
^^)acknowledgements)

\section REFERENCES.

\dref{Bowman} J.~Bowman, Ph.D. thesis, Princeton University, 1992.

\dref{Knuth} D.~E. Knuth, {\sl Literate Programming} (Center for the Study
of Language and Information, Leland Standard Junior University, 1992).

\dref{KP} B.~W. Kernighan and P.~J. Plauger, {\sl Software Tools}
(Addison-Wesley, Reading, Massachusetts, 1976).

\dref{makeindex} The {\tt makeindex} utility is available from
{\tt ftp.math.utah.edu} in {\tt /pub/tex/pub/makeindex/2-11}.  The
extension~{\tt .trz} is equivalent to~{\tt .tar.Z}.

\dref{Speh} Marcus Speh, {\tt marcus@x4u.desy.de}.  For further information,
see the files in the official \FWEB\ public area:
{\tt lyman.pppl.gov:/pub/fweb/faq}.

\manrefs

\vfill\Eject

\section APPENDICES.[19.13]

\Knuth
The basic ideas of \.{WEB} can be understood most easily by looking at
examples of ``real'' programs. Appendix~A shows \[the \.{FWEB} input for the
simple \Fortran\ to \FWEB\ ^{demo program} \.{f\_to\_web}\];
Appendix~B shows the corresponding \TeX\ code output by
\.{FWEAVE}; \[Appendix~C shows excerpts from the finished woven product
typeset from \.{f\_to\_web.tex};\] and Appendix~\[D\]
shows the corresponding code output by \.{FTANGLE}.  \[Appendix~E shows the
woven output from the sample \.{f90\_cpp.web}, which mixes \Cpp\ and
\Fortran--90 code.\]

The complete webs for \.{FWEAVE} and \.{FTANGLE} \[are available in the files
\.{fweave.web} and \.{ftangle.web}. It's very instructive to study these
programs\], since \.{WEAVE} and \.{TANGLE} contain several interesting
aspects, and since an attempt has been made in these \[codes\] to evolve a
style of programming that makes good use of the \.{WEB} language.

Appendix~F is the `\.{fwebmac}' file that sets \TeX\ up to accept the
output of \.{FWEAVE}; Appendix~G discusses how to use some of its macros to
vary the output formats; \[Appendix~H summarizes how this \.{FWEB} code
differs from its immediate predecessor \.{CWEB}\].  \[Appendix~I is a
question-and-answer session about \FWEB,\] and Appendix~J discusses what
needs to be done when \.{FWEAVE} and \.{FTANGLE} are installed in a new
operating environment.

Appendix~K lists and explains the error
messages produced by \FWEB. Finally,
Appendix~L contains a summary of all the \FWEB\ syntax, commands,
and idiosyncracies.

% Here is a quotation that could not really be omitted.

\vfill

{\baselineskip9pt
\halign to\hsize{\hfil\quoteit#\tabskip 0pt plus 100pt&
  \hfil\quoteit#\tabskip 0pt\cr
O, what a tangled web we weave&
  O, what a tangled WEB we weave\cr
When first we practise to deceive!&
  When \TeX\ we practise to conceive!\cr
\noalign{\vskip 2pt}
\quoterm ---SIR WALTER SCOTT, {\quoteit Marmion} 6:17 (1808)&
  \quoterm ---RICHARD PALAIS (1982)\cr
}}
^^{Scott, Sir Walter} ^^{Palias, R.}

\Eject

% ------------------------------ APPENDICES ------------------------------

\appendix A: A SIMPLE DEMO PROGRAM:
{\tt f\_to\_web.web}.[{\tt f\_to\_web.web}]

^^(\>{f\UL to\UL web}!\>{.web}(
Appendices A--D use a simple \Fortran--77 program to demonstrate the various
facets of the \WEB\ system.  The demonstration begins with the file
\.{f\_to\_web.src}, provided with the \FWEB\ distribution but not shown
here.  This appendix is a verbatim listing of a \.{web} file based on
\.{f\_to\_web.src}. Appendix~B shows the output \.{f\_to\_web.tex} from
\FWEAVE, Appendix~C 
shows part of the finished typeset product, and Appendix~D is a verbatim
listing of the output from \FTANGLE.
\HRULE

\verbatim{f_to_web.web}
^^)\>{f\UL to\UL web}!\>{.web})

\appendix B: WOVEN OUTPUT {\tt f\_to\_web.tex}.[{\tt f\_to\_web.tex}]

The following output \.{f\_to\_web.tex} results from the command ``\.{fweave f\_to\_web}''.
\HRULE
^^(\>{f\UL to\UL web}!\>{.tex}!raw output(
\verbatim{f_to_web.tex}
^^)\>{f\UL to\UL web}!\>{.tex}!raw output)

\appendix C: The FINISHED PRODUCT {\tt f\_to\_web}.[FINISHED PRODUCT]

^^(\>{f\UL to\UL web}!\>{.tex}!typeset output(
Here is part of the typeset documentation produced by saying 
``\.{tex f\_to\_web.tex}'' and printing the output \.{f\_to\_web.dvi}.
\HRULE
\typeset{f_to_web}
\HRULE

^^)\>{f\UL to\UL web}!\>{.tex}!typeset output)

\appendix D: TANGLED OUTPUT {\tt f\_to\_web.f}.[{\tt f\_to\_web.f}] 

The following output results from the command ``\.{ftangle f\_to\_web}''.
^^(\>{f\UL to\UL web}!\>{.f}(
\HRULE

\verbatim{f_to_web.f}
^^)\>{f\UL to\UL web}!\>{.f})


\appendix E: EXAMPLE of {\tt C++} and {\tt Ratfor--90} CODE.[MODERN LANGUAGES]

This example demonstrates some sample \Ratfor--90 and \Cpp~code that
involves operator overloading.  Note how the \atcmd{v}~command is used to
change the default printed form of the overloaded operators.

\HRULE
\typeset{f90_cpp}
\HRULE

\appendix F: The {\tt FWEBMAC} MACROS.[MACROS]

\iftypesetfwebmac
	\typeset{fwebmac}
\else
	If this appendix is not here, you can say \.{\\typesetfwebmactrue}
near line~39 of \.{fwebman.tex} to create a larger, self-contained manual.
Alternatively, you can weave \.{fwebmac.web} separately.
\fi

\appendix G: HOW TO USE {\tt FWEB} MACROS.[NOTES on FORMATTING][19.7.20]

The macros in \.{fwebmac.sty} (produced by tangling \.{fwebmac.web}) make
it possible to produce a variety of formats 
without editing the output of \.{FWEAVE}, and the purpose of this appendix
is to explain some of the possibilities.  \It{(NOTE:  Although \FWEB\ now
works with \LaTeX, the original discussion in this appendix was for Plain
\TeX, and it may have not been completely updated yet.)}
\endKnuth

Before proceeding, it is important to stress that it is sometimes not possible
to satisfactorily change the appearance of the woven output just by
modifying macros in \.{fwebmac}. Occasional difficulties may arise since
certain
\TeX\ commands are hard-coded into \.{FWEAVE}'s output routines. In unusual
situations, one may need to recompile \.{FWEAVE} to achieve the desired effect.
(But don't do this unless you really have to; it can be an endless sink of
time.)  However, many features can be customized via the style file.
(Please feel free to suggest additional features that should be customizable.)

\Knuth
\gdef\point#1.{\subsubsection#1.\par}
\newfeature

\point Additional fonts. \[Several\] ^{fonts} have been declared in
addition to the standard fonts of 
\.{PLAIN} format: You can say `\.{\{\\SC STUFF\}}' to get {\SC STUFF}
in small caps, \[or `\.{\{\\Csc Stuff\}}' to get {\Csc Stuff}\]; 
^^:\CS{SC}: ^^:\CS{Csc}: ^^:fonts!small caps\actual{\SC SMALL CAPS}:
^^:fonts!caps/small caps\actual{\Csc CAPS/small caps}: 
and you can select the largish fonts \.{\\titlefont} and \.{\\ttitlefont}
in the title of your document, where \.{\\titlefont} ^^:\CS{titlefont}:
gives one {\titlefont titlefont} and \.{\\ttitlefont} ^^:\CS{ttitlefont}:
is a typewriter style of type giving one {\ttitlefont ttitlefont}.

\point Typesetting comments. Comments are typeset in the font
\.{\\cmntfont}, ^^:\CS{cmntfont}: ^^:fonts!comment:
which is \.{\\let} to \.{\\tenrm} ^^{\CS{tenrm}}
by default.  You can redefine \.{\\cmntfont} in the
limbo section;  ^^{limbo!section}
for example, ``\.{\\let\\cmntfont\\Csc}''.

\point Typesetting identifiers. ^^[identifiers!typesetting]
When you mention an identifier in \TeX\
text, you normally call it `\.{|identifier|}'. But \[if that identifier is
not a 
reserved word\], you can also say `\.{\\\\\{identifier\}}'.  ^^:\CS{\BS}:
The output will look the same in both cases, \[namely `\\{identifier}'\],
but the second alternative doesn't put \\{identifier} into the index, since
it bypasses \.{WEAVE}'s translation from \[code\] mode. \[For one-character
identifiers, you should say `\.{\\|i}' to get `\\i'. ^^:\CS{"|}: Also, for
a reserved 
word you can say `\.{\\\&\{reserved\}}' to get `\&{reserved}'. ^^:\CS{\amp}:
If you're
talking about an intrinsic function, you can say '\.{\\@@\{intrinsic\}}' to
get `\IF{intrinsic}'. ^^:\CS{@}: (Note that the macro name itself is
`\.{\\@}'.)\] 

Note that \WEB\ identifiers may contain the characters~`\.\$' and~`\.\_'.
These must be preceded by a backslash when using them with the
macros~\.{\\\\},
\.{\\\&}, and~\.{\\@}.  This is not necessary when enclosing such
identifiers between vertical bars; \WEB\ handles the escaping for you.
Thus, say ``\.{|id\_code|}'' but ``\.{\\\\\{id\\\_code\}}''.

^^{LaTeX:\LATEX}
\LaTeX\ users (see the section below on Using \LaTeX)
will object that `\.{\\\\}'~means something very different to
them.  Actually, the true situation is slightly more complicated than that
described in the last paragraph.  In \.{fwebmac}, the macro that
formats an ordinary identifier is really called~`\.{\\Wid}', ^^:\CS{Wid}:
not~`\.{\\\\}'.
The macro~`\.{\\\\}' becomes associated with~`\.{\\Wid}' because the
style-file entry `\.{format.identifier}' has~`\.{\\\\}' as its default
value.  That value is transmitted to \TeX\ or \LaTeX\ via the
`\.{\\Wbegin}' macro ^^:\CS{Wbegin}:
that is emitted automatically just after the ``\.{\\input fwebmac.sty}''
command at the beginning of the output file.  (Study a sample of woven
output, for example Appendix~B.)  Similar equivalences are set up for the
other formatting macros according to the following table:
\input equiv
^^:\CS{Wreserved}:  ^^:\CS{Wshort}:  ^^:\CS{Wid}:  ^^:\CS{WidD}:
^^:\CS{WidM}: ^^:\CS{Wintrinsic}:  ^^:\CS{Wkeyword}:  
Note that by default macro names are treated the same way as ordinary
identifiers.  To cause macro names to be formatted in a distinctive way,
you must use the style-file entries \.{format.outer\_macro} and/or
\.{format.WEB\_macro}. 
^^{macro!outer!formatting} ^^{macro!inner!formatting}
(If more than one of these has the same value, the equivalences to the
fundamental definitions in \.{fwebmac.sty} are made in the order
\.{format.WEB\_macro}, \.{format.outer\_macro}, then \.{format.identifier}.)
However, you must \It{also} supply a new definition
for the \.{fwebmac} macros~\.{\\WidD} and/or~\.{\\WidM}, 
^^{\CS{WidD}} ^^{\CS{WidM}}
since by default
these are merely \.{\\let} equal to~\.{\\Wid}.  You could introduce such
new definitions by placing them into a file that is \.{\\input}
automatically at the beginning of each run (see the style-file entry
\.{limbo}), ^^{style file!vocabulary!\>{limbo}}
by creating a new personal version of \.{fwebmac.sty}
^^{\>{fwebmac}!\>{.sty}!personal version of}
(use a change file in conjunction with \.{fwebmac.web}), or by using the
\atcmd{l}~command ^^{\>{@l}}
to place the definition directly into the limbo section of your code.

\point Typewriter type.  ^^[fonts!\>{typewriter}]
To get typewriter-like type, as when referring to
`\.{WEB}', you 
can use the `\.{\\.}' macro (e.g., `\.{\\.\{FWEB\}}'). ^^{\CS.}
In the argument to
this macro you should insert an additional backslash before the \[following
characters enclosed by double quotes: ``\.{\ \\\#\%\$\^\{\}\~\&\_}''\].
A `\.{\\\ }' here will result in the visible space ^^{space!visible}
symbol; to get an invisible space ^^{space!invisible}
following a control sequence you can say `\.{\{\ \}}'.
\endKnuth

The original form of the `\.{\\.}' macro surrounded the string with an
\.{\\hbox}, which unfortunately
prevented very long strings from being broken across lines. The present
\FWEB\ form does \It{not} surround the string with an \.{\\hbox} and allows
strings to be broken, either after commas or every so many characters. To
accomplish this, \FWEAVE\ inserts into strings special control sequences
that are treated essentially like discretionary hyphens. Automatically
broken strings are marked by a backslash at the end of the line.

Actually, the \.{fwebmac} macro for typewriter type is called
`\.{\\Wtypewriter}'.  ^^:\CS{Wtypewriter}:  ^^{style
	file!vocabulary!\>{format.typewriter}} 
Its equivalence to~`\.{\\.}' is established by the
same mechanism as described above for formatting identifiers, via the
style-file entry `\.{format.typewriter}'. 

\Knuth
\point Page dimensions.  ^^[page!dimensions]
The three control sequences \.{\\pagewidth}, \.{\\pageheight}, 
and \.{\\fullpageheight} 
^^:\CS{pagewidth}: ^^:\CS{pageheight}: ^^:\CS{fullpageheight}:
can be redefined in the limbo section ^^{limbo!section}
at the 
beginning of your \.{WEB} file to change the dimensions of each page.
The standard settings
$$\lpile{\.{\\pagewidth=6.5in}\cr
  \.{\\pageheight=8.7in}\cr
  \.{\\fullpageheight=9in}\cr}$$
were used to prepare the present report; \.{\\fullpageheight} is
\.{\\pageheight} plus room for the additional heading and page numbers at
the top of each page. If you change any of these quantities, you should
call the macro \.{\\setpage} immediately after making the change.

\point Page heads. ^^[page!heads] ^^:\CS{identicalpageheads}:
The macro \.{\\identicalpageheads} is normally false, which means that by
default the page numbers and module numbers will alternate left and right
on even- and odd-numbered pages.  If you want all the page heads to be
formatted identically, say ``\.{\\identicalpageheadstrue}''.


\point Shifting pages left or right. ^^[page!shifting] ^^:\CS{pageshift}:
The \.{\\pageshift} macro defines an amount by which right-hand
pages (i.e., odd-numbered pages) are shifted right with respect to
left-hand (even-numbered) ones. By adjusting this amount you may be
able to get two-sided output in which the page numbers line up on
opposite sides of each sheet.

\point Page title. ^^[page!title] ^^[title] ^^:\CS{Wtitle}:
The \.{\\Wtitle} macro will appear at the top of each page
in small caps.   This macro is null by default, but you can define it in
the limbo section.
\comment
For example, Appendix~D was produced after saying
`\.{\\def\\Wtitle\{WEAVE\}}'.
\endcomment

\point Page numbering. ^^[page!numbering] ^^{\CS{pageno}}
The first page usually is number 1; if you want some other
starting page, just set \.{\\pageno} to the desired number---e.g.,
`\.{\\pageno=16}'.
\endKnuth

\point Paragraph breaks.  ^^[paragraph breaks] 
By default, paragraph breaks in \TeX\ mode are spaced out with an
extra blank line. If you don't want that, say `\.{\\pardimen=0pt}'.
^^:\CS{pardimen}:

\point Magnifying the output. ^^[output, magnifying] ^^[page!magnification]
^^:\CS{magnify}: 
If you want your output to be bigger than usual, use 
\.{\\magnify} instead of  \.{\\magnification}; say, for example,
`\.{\\magnify\{\\magstep1\}}'. 

\Knuth
\point Table of contents. ^^[table of contents]
^^{\CS{iftitle}} ^^:\CS{titletrue}: ^^:\CS{titlefalse}: 
The macro \.{\\iftitle} will suppress the header line if it is defined by
`\.{\\titletrue}'. The normal value is \.{\\titlefalse} except for the
table of contents; thus, the contents page is usually unnumbered. If your
program is so long that the table of contents doesn't fit on a single page,
or if you want a number to appear on the contents page, you should reset
\.{\\pageno} when you begin the table of contents.

^^:\CS{topofcontents}: ^^:\CS{botofcontents}:
Two macros are provided to give flexibility to the table of
contents: \.{\\topofcontents} is invoked just before the contents
info is read, and \.{\\botofcontents} is invoked just after.
For example, Appendix~D of Knuth's original manual was produced with the
following definitions: 
$$\lpile{\.{\\def\\topofcontents\{\\null\\vfill}\cr
  \.{ { }\\titlefalse \% include headline on the contents page}\cr
  \.{ { }\\def\\rheader\{\\mainfont Appendix D\\hfil 15\}}\cr
  \.{ { }\\centerline\{\\titlefont The \{\\ttitlefont WEAVE\}{ }processor\}}\cr
  \.{ { }\\vskip 15pt \\centerline\{(Version 2.5)\}{ }\\vfill\}}\cr}$$
Redefining \.{\\rheader}, which is the headline for right-hand pages,
suffices in this case to put the desired information at the top of the page.

\point Customizing the table of contents. ^^[table of contents!customizing]
^^:\>{CONTENTS.tex}: 
Data for the ^{table of contents} is written to a file that
is read after the indexes have been \TeX ed; there's one line of data
for every starred module. For example, one might obtain
a file \.{CONTENTS.tex} ^^{\>{CONTENTS.tex}}
containing
$$\lpile{\.{\\WZ \{0\}\{{ }Introduction\}\{1\}\{16\}}\cr
  \.{\\WZ \{0\}\{{ }The character set\}\{11\}\{19\}}\cr}$$
and similar lines. Here the first argument of~\.{\\WZ} ^^:\CS{WZ}:
is the level number of the
module, the second argument is the title, the third is the module number,
and the fourth is the page number.
The \.{\\topofcontents} macro ^^{\CS{topofcontents}}
could redefine \.{\\WZ} so that the information appears in another format.
(The default name \.{CONTENTS.tex} can be changed by means of the
style-file parameter ``\.{contents.tex}''.
^^{style file!vocabulary!\>{contents.tex}}

\point Date and time. ^^[date] ^^[time] ^^:\CS{Date}: ^^:\CS{Time}:
The macro \.{\\Date} gives the present date in the form ``\Date''.
The macro \.{\\Time} gives the time in the form ``\Time''. By default,
these are printed automatically at the bottom of the title page, via the
\.{\\botofcontents} macro.

\point Subdividing output. ^^[output!subdividing]
Sometimes it is necessary or desirable to divide the output of
\.{WEAVE} into subfiles that can be processed separately. For example,
the listing of \TeX\ runs to more than 500 pages, and that is enough to
exceed the capacity of many printing devices and/or their software.
When an extremely large job isn't cut into smaller pieces, the entire
process might be spoiled by a single error of some sort, making it
necessary to start everything over.

Here's a safe way to break a woven file into three parts:
Say the pieces are $\alpha$,
$\beta$, and $\gamma$, where each piece begins with a starred module.
All macros should be defined in the opening limbo section ^^{limbo!section}
of $\alpha$,
and copies of this \TeX\ code should be placed at the
beginning of $\beta$ and of $\gamma$. In order to process the parts
separately, we need to take care of two things: The starting page
numbers of $\beta$ and $\gamma$ need to be set up properly, and
the table of contents data from all three runs needs to be
accumulated.

^^:\CS{contentsfile}: ^^:\CS{readcontents}:
The \.{webmac} macros include two control sequences \.{\\contentsfile} and
\.{\\readcontents} that facilitate the necessary processing.  We include
`\.{\\def\\contentsfile\{CONT1\}}' in the limbo section of $\alpha$, and
we include `\.{\\def\\contentsfile\{CONT2\}}' in the limbo section of
$\beta$; this causes \TeX\ to write the contents data for $\alpha$ and $\beta$
into \.{CONT1.TEX} and \.{CONT2.TEX}. Now in $\gamma$ we say
$$\hbox{\.{\\def\\readcontents\{\\input CONT1 \\input CONT2 \\input
CONTENTS\}}};$$ 
this brings in the data from all three pieces, in the proper order.

However, we still need to solve the page-numbering problem. One way to
do it is to include the following in the limbo material for $\beta$:
$$\lpile{\.{\\message\{Please type the last page number of part 1: \}}\cr
  \.{\\read-1to\\\\ \\pageno=\\\\ \\advance\\pageno by 1}\cr}$$
Then you simply provide the necessary data when \TeX\ requests
it; a similar construction is used at the beginning of $\gamma$.

This method can, of course, be used to divide a woven file into
any number of pieces. \[(One problem with it is that each piece will have its
own index. This problem will be addressed in the future.)\]

\point Special index entries.  ^^[index!entry]
Sometimes it is nice to include things in the index that are
typeset in a special way. For example, we might want to have an
index entry for `\TeX'. \.{WEAVE} provides only two standard ways to
typeset an index entry (unless the entry is an identifier, an intrinsic
function, or a reserved word): 
\atcmd{\^}~gives roman type, and \atcmd{.}~gives \.{typewriter} type.
But if we try to typeset `\TeX' in roman type by saying, e.g.,
\atcmd{\^\\TeX@>}, the backslash character gets in the way,
and this entry wouldn't appear in the index with the T's.

The solution is to use the \atcmd{9}~feature,  ^^{\>{@9}} ^^{\CS9}
declaring a macro that
simply removes a sort key as follows:
$$\hbox{\.{\\def\\9\#1\{\}}}$$
Now you can say, e.g., \atcmd{9TeX\}\{\\TeX@>} in your \.{WEB} file; \.{WEAVE}
puts it into the index alphabetically, based on the sort key, and
produces the macro call `\.{\\9\{TeX\}\{\\TeX\}}' which will ensure that
the sort key isn't printed.

A similar idea can be used to insert hidden material into module
names so that they are alphabetized in whatever way you might wish.
Some people call these tricks ``special refinements''; others call
them ``kludges''. ^^:kludges: ^^:refinements, special:

\point Module number. ^^:\CS{modno}:
The control sequence \.{\\modno} is set to the number of the
module being typeset. 
\endKnuth

\point Symbolic names of modules. ^^[modules!symbolic names of]
^^:\CS{modlabel}: ^^:\CS{module}: ^^:\CS{WEBmodule}: ^^:\CS{WEBsection}:
The macros \.{\\modlabel} and \.{\\module} afford a way of assigning
symbolic names to modules (whose absolute numbers one doesn't know). Say
\.{\\modlabel\{alpha\}} somewhere in the module in question. If somewhere else
you want to discuss that particular module, say something like
`\.{discussed in \\module\{alpha\}}'. With Plain \TeX,
forward references do not work; you
must label the module before you reference it with \.{\\module}.  (However,
the scheme could be generalized in standard ways, using the I/O features of
\TeX.)  When \LaTeX\ is in use, ^^{LaTeX:\LATEX}
forward references \It{do} work; the
definitions of the module labels are stored in the \.{.aux} file, ^^{\>{.aux}}
using \LaTeX's \.{\\label} macro.  ^^{\CS{label}}
In fact, under \LaTeX\ the definitions of \.{\\modlabel} and \.{\\module}
are equivalent to simply 
\begintt
\def\modlabel#1{\label{MOD#1}}
\def\module#1{module~\ref{MOD#1}}
\endtt
If you want to say ``section'' instead of ``module'', say
``\.{\\WEBsection}'' instead of ``\.{\\module}''.  (\LaTeX\ usurps
``\.{\\section}''.) For symmetry, ``\.{\\WEBmodule}'' is equivalent to
``\.{\\module}''. 

\Knuth
\point Listing modules that have been changed. ^^[modules!listing changed]
^^:\CS{maybe}:
If you want to list only the modules that have changed,
together with the index, put the command `\.{\\let\\maybe=\\iffalse}' in
the limbo section before the first module of your \.{WEB} file. It's
customary to make this the first change in your change file.
\endKnuth

\point Loading the macro package. ^^[\>{fwebmac}!\>{.sty}!loading]
^^:\CS{ifWEB}: ^^:\CS{ifFWEB}: ^^:\CS{WEBisloaded}: ^^:\CS{FWEBisloaded}: 
The macro package \.{fwebmac.sty} \.{\\let}s~the macro
\.{\\FWEBisloaded} to be \.{\\relax}. This macro
can be used in various ways by macros you write that may need to behave
differently depending on whether \.{fwebmac} has been loaded or not. See
the Dirty Tricks section of the \TeX book.

\point Redefined macros.
The macro package \.{fwebmac} usurps certain macro names for its own
use.  To find a complete list of the \.{fwebmac} macros, look in the index
to \.{fwebmac.tex}.  The original definitions of some of the more common
ones are stored away under other names, as follows:
^^:\CS{amp}: ^^{\CS{\amp}}
^^:\CS{at}:  ^^{\CS{@}}
^^:\CS{bslash}: ^^{\CS{\BS}}
^^:\CS{caret}: ^^{\CS{\^}}
^^:\CS{dollar}: ^^{\CS{\dollar}}
^^:\CS{dstar}: ^^{\CS{*}}
^^:\CS{equals}: ^^{\CS{=}}
^^:\CS{leftbrace}: ^^{\CS{\LB}}
^^:\CS{period}: ^^{\CS.}
^^:\CS{rightbrace}: ^^{\CS{\RB}}
^^:\CS{vertbar}: ^^{\CS{"|}}
^^:\CS{PM}: ^^{\CS{\PM}}
^^:\CS{PC}: ^^{\CS{\PC}}
\begintt
\let\amp\&
\let\at\@
\let\bslash\\
\let\caret\^
\let\dollar\$
\let\dstar\*
\let\equals\=
\let\leftbrace\{
\let\period\.
\let\rightbrace\}
\let\vertbar|
\let\PM\#
\let\PC\%
\endtt

\point Using {\tt FWEB} with \LaTeX. ^^[LaTeX:\LATEX]
The \WEB\ system was originally designed for use with Plain \TeX, and the
design of the macros in \.{fwebmac} reflects this.  However, with some
restrictions it is 
also possible to use \FWEB\ with \LaTeX, thereby gaining the use of
additional convenient macros, environments, etc.  To use \LaTeX\ instead of
\TeX\ to process the output \.{test.tex} that results from running \FWEAVE\
on \.{test.web}, you should do two things at a minimum:  

{\narrower
\item{(1)} Use the command-line option `\.{-PL}'.  ^^{\={-p}{-P}}
^^{\TeX\ processor, selecting}
(If you will always be using \LaTeX, place the command `\.{+PL}' into your
\.{.fweb} file.) ^^{\>{.fweb}}
This command affects the default definitions of certain quantities defined
through the style file; see the discussion below.

\item{(2)} Simply say ``\.{latex test}'' instead of ``\.{tex test}''.

}

\parinsert{4}{4}{0.4}
Just say ``{\ssbf latex test}'' instead of ``{\ssbf tex test}''.

Probably the principal
price one pays is that \FWEB\ has already usurped certain macro names for
its own use.  For example, the standard \FWEB\ macro used to format an ordinary
identifier is~`\.{\\\\}'. See the table just above for alternative macro
names.  For example, a \LaTeX\ user could use `\.{\\bslash}' instead
of~`\.{\\\\}'.  
However, since the use of~`\.{\\\\}' is quite common in \LaTeX\ and
it is cumbersome to type `\.{\\bslash}' 
it is possible to dynamically reconfigure \FWEAVE\ to use a
different macro to format ordinary identifiers.  This is done through the
style file.  As explained above in the section on ``Typesetting
identifiers,'' the names of the identifiers actually used in the \.{tex}
file to format identifiers are mapped through an equivalencing procedure to
the actual definitions in \.{fwebmac}, and those names can be changed
without tampering with the definitions through entries in the style file.
If no entries are made in the style file, then by default the
macro~`\.{\\\\}' is used to format both outer macro names, \WEB\ macro
names, and ordinary identifiers (with more than one character).  When the
`\.{-PL}'~option is used, then that default is instead chosen to
be~`\.{\\>}'.  That default can be overridden by explicit style-file entries.

Additional difficulties will arise with certain attempts to produce very clever
output using some of the page layout facilities of \LaTeX, since \FWEB\
overrides the \.{\\output} ^^{\CS{output}}
routine of \LaTeX.  

Also, \LaTeX's \.{\\index} macro ^^{\CS{index}}
is not correlated in any way to the index produced by \FWEAVE.

On the positive side, the use of the \.{aux} ^^{\>{.aux}}
file allows forward referencing to module names to be done conveniently.
In particular, \LaTeX's \.{\\label} macro ^^{\CS{label}}
understands the current module
number.  (It does \It{not} understand anything about the level of starred
modules.) See the discussion about ``Symbolic names of modules'' above.

Beginning with version~1.30 the \.{fwebmac} macros have been augmented
(thanks to Charles Karney) ^^{Karney, Charles}
to work with \LaTeX's New Font Selection Scheme (NFSS).  
^^{NFSS} ^^{fonts!selecting}
There hasn't been too much experience here; please report any difficulties.

\appendix H: SUMMARY of EXTENSIONS or CHANGES FROM {\tt CWEB}.[CHANGES FROM
{\tt CWEB}]

\It{Here are some of the more significant differences between \CWEB\ and
\FWEB~1.0. Many more features have been added in v.~1.1 and later;
these are too numerous to describe here.}

Blank lines in the source are significant to \WEAVE. The \atcmd{\#}~command
will hardly ever have to be used. 

The unnamed module is begun by~\atcmd{a}.

Language switching: the \atcmd{c}, \atcmd{r}, and \atcmd{n}~commands.

Long strings (`\.{\\.}' macro)
are broken with discretionary backslashes every so many characters, 
and after commas.

Verbatim comments: Preface comments you want \TANGLE\ to keep by~\atcmd{},
as in `\atcmd{/*\ Keep.\ */}'.
Make all comments verbatim by command-line option~`\.{-v}'.

\WEB\ macros, defined by \atcmd{m} and expanded by \TANGLE, were reintroduced.
Macro definitions are allowed in the code section.

A \C-like preprocessing language was added. The preprocessor commands may
appear in either the definition section or the code section. 

\FTANGLE\ translates \Ratfor\ directly to \Fortran.

One-character uppercase \.{fwebmac} macros have been changed to
two-character ones starting with~`\.{W}'.

Because physicists sometimes like to use the asterisk for complex
conjugation and therefore may define it to be an active character, \FTANGLE\
will output an asterisk when it is in \TeX\ mode, but puts out
``\.{\\ast}'' when it is in code mode. 

\appendix I:  \FWEB\ Q and A.[Q and A] ^^[questions] ^^[answers]

\def\Q#1\par{\noindent{\bf Q.\enspace}{\it\ignorespaces#1}\par}
\def\A#1\par{{\narrower\noindent\hang{\bf A.\enspace}\ignorespaces#1\par}}

\It{This section is not complete!} Please see \.{/pub/fweb/faq} for a more
complete discussion\cite{Speh}.

\Q What is the difference between \.{fwebmac.web}, \.{fwebmac.tex}, and
\.{fwebmac.sty}? 

^^{\>{fwebmac}!\>{.web}} ^^{\>{fwebmac}!\>{.tex}} ^^{\>{fwebmac}!\>{.sty}} 

\A The macros read in by the \.{*.tex} files produced by \FWEAVE\ are
called \.{fwebmac.sty}; they are maintained in the source file
\.{fwebmac.web}.  Running \FTANGLE\ on \.{fwebmac.web} produces
\.{fwebmac.sty}; if you want to see a pretty listing of the macros, run
\FWEAVE\ on the source to get \.{fwebmac.tex}.


\Q Why not incorporate Pascal ^^{language!Pascal}
as one of the supported languages, especially
since Knuth's original processors supported that?

\A This project evolved from Levy's \CWEB, which was written in~C for~C.
Since the present author does not personally use Pascal, it was considered
too much of an effort to incorporate Pascal processing, especially since
most modern codes are written in~C.


\Q What is the difference between \.{.fweb} and \.{fweb.sty}?
^^{\>{.fweb}} ^^{\>{fweb.sty}}

\A Both are initialization files.  However, \.{.fweb} is intended to be
a global initialization file for all runs made by a particular author.  One
is supposed to put common command-line options into here.  The style file
\.{fweb.sty} is intended to allow customizations of particular runs or
groups of runs.  For example, the appearance of the index can be customized
by setting parameters in the style file.  Also, \.{.fweb}~is read
\It{before} the command line is processed, while \.{fweb.sty}~is read
\It{after} \.{.fweb} and the command-line are processed.

\Q How does one force \FWEAVE\ to align comments?
^^{comments!aligning}

\A One can't do that yet.  In general, all complicated alignment issues
relating to \FWEAVE\ have been deferred to a future version.  Sorry!

\It{This list is not completed yet. Please suggest questions to be
discussed in this space.} 

\appendix J: ERROR MESSAGES.[][19.11.5]
^^(error messages(

\def\errorclass#1\par{\subsubsection #1\par}
%\bigskip\leftline{\bf #1:}\nobreak}
\def\error#1#2\par{\noindent\hang{\bf ``#1.''}\enspace\ignorespaces#2\par}
\parskip=\pardimen

Presently the error- message-processing facilities are a mixture of old and
new: the original scheme of Knuth and Levy was restricted to function calls
with fixed 
number of arguments, which tended to result in error messages with the bare
minimum of information. Many, although not yet all, of the error messages have
now been generalized to calls allowing variable numbers of arguments, which
facilitates constructing rather elaborate error messages. Error processing
will be refined still further in the future. \It{It is very important that
you report difficulties with \FWEB's error processing facilities.} If
\FWEB\ ever issues an error not in the following list, please report that too.

There are five general classes of error messages: (1)~messages common to
both \FTANGLE\ and \FWEAVE\ (produced, for example, by command-line
processing or one of the input drivers); 
(2)~general
messages from \FTANGLE; (3)~macro processing errors; (4)~\Ratfor\ errors;
(5)~general messages from \FWEAVE.  The class of the error is (usually)
indicated in the output to the screen.
There is as yet no numbering scheme. The
messages are described here alphabetically within each class. Italics
indicate variable fields that are filled in by the particular situation.

\errorclass Messages common to both {\tt FTANGLE} and {\tt FWEAVE}.
^^(error messages!common to both processors(

\error{Ambiguous prefix} A section name abbreviated with an ellipsis was
not unique.

\error{Can't open include file \."\It{name}\."} Possibly a misspelled file
name; the \.{@i} command is skipped.

\error{\.{get\_mem0}:  Can't request $n$~units; used max of~$n$}
Either you're asking for too much memory, or there's something wrong with
the use of the ANSI \\{calloc} routine.  If you think it's the latter,
please report it.

\error{Change file ended after \.{@x}} There's something missing.

\error{Change file ended before \.{@y}} You must use the complete
construction \.{@x}\dots\.{@y}\dots\.{@z}.

\error{Change file ended without \.{@z}} You must  use the complete
construction \.{@x}\dots\.{@y}\dots\.{@z}.

\error{Change file entry did not match} There's no text in the \WEB\ file
that matches the stuff between~\.{@x} and~\.{@y}.

\error{\.{get\_mem0}: Can't request $n$~units; used max of $m$} This is
probably related to the difference between \&{int}s and \&{long}s on the local
machine, and may signify a bug in the implementation.

\error{Hmm\dots\ some of the preceding lines failed to match} There was
stuff left in the change buffer at the end of the run.

\error{\.{get\_mem0}: Can't request $n$~units; used max of $m$} This is
probably related to the difference between \&{int}s and \&{long}s on the local
machine, and may signify a bug in the implementation.

\error{Hmm\dots\ some of the preceding lines failed to match} There was
stuff left in the change buffer at the end of the run.

\error{Input line too long; must be shorter than \It{n} characters} The
input line length may be increased with the \.{-mbs} option.

\error{Invalid 'g' option: parameter type $c$}.  The valid parameters
are~'\.r', '\.m', or~'\.s'.

\error{Invalid 'g' option: \dots} You specified an invalid parameter for the
\Ratfor\ \&{switch}.

\error{Invalid language command "\dots"} You said \atcmd{L$l$}, where
$l$~was not one of~'\.c', '\.n', '\.r', or~'\.x'.

\error{Missing id for \.{'m'} option} To define a macro from the command
line, you must say \.{-mA=1} or \.{-m"A\ 1"}.

\error{Missing id for \.{'u'} option} You must say \.{-u\It{name}}.

\error{Missing language character after~\.{@L}} You must say~\atcmd{L$l$}.

\error{No includes allowed in change file} You may not use the \.{@i}
command within a change file.

\error{Style file name too long; must be less than $n$~characters} There's
something wrong with the \.{-z} option.

\error{Syntax error in output redirection command \.{"->"}. Language must
be one of \.{'c'}, \.{'r'}, or \.{'n'}, not \.{'$x$'}} If you're
redirecting output from a particular language, the form of the command is
``\.{->$l$=\It{file}}''.

\error{Too many nested includes; $n$~allowed} \.{@i}~commands can be nested
to a level of~$n$.

\error{WARNING: Command-line language \It{name} overridden in limbo by
\It{new\_name}} A language command in the limbo section always takes
precedence over a language specified on the command line.

\error{WEB file ended during a change} There's something incompatible about
the change you're trying to make.

\error{Where is the matching \.{@x}?} In the change file, a~\.{@y}
or~\.{@z} was encountered before an \.{@x}.

\error{Where is the matching \.{@y}?} A misplaced \.{@x} or~\.{@z} was
encountered. 

\error{Where is the matching \.{@z}?} A misplaced \.{@x} or~\.{@y} was
encountered. 
^^)error messages!common to both processors)

\errorclass General messages from {\tt FTANGLE}.
^^(error messages!\>{FTANGLE}(

\error{@d, @f, and @a are ignored in code text} \.{@d} and~\.{@f} may
appear only in the definition section. \.{@a}, which signifies the unnamed
module, must be preceded by either \.{@\ } or \.{@*}.

\error{ASCII string didn't end} ASCII constants such as \.{@'a'} must end
on the same input line as they begin. (They can't even be continued by
backslashes.)

\error{Can't continue comments on \.{@i}~lines} You said something like
`\atcmd{i\ \It{filename}\ /*\dots}'.

\error{Code text flushed; \.= sign is missing} A section name of the form
\.{@<\dots@>} was encountered at the end of a \TeX\ or definition section,
but it wasn't followed by the requisite equals sign that signifies the
start of a named module.

\error{Compiler directives are allowed only in code} The compiler directive
command~\.{@!} was encountered while scanning through \TeX\ text.  This
directive is allowed only in the code section.

\error{Continuation character \.{'$c$'} from \.{'\&'} option is invalid;
\.{'$d$'} assumed} \Fortran's continuation character must be printable and
not blank. 

\error{Definition flushed; must start with identifier} An \.{@d} or~\.{@m}
command must be followed by a valid identifier.

\error{Expected \.{@>} after \.{@<}} A section name must be indicated by
\.{@<\dots@>}. 

\error{Expected '$c$' after language in "\.{->}"; command ignored} The
syntax of the output redirection command is ``\.{->$l$=\It{filename}}''.

\error{Improper \.@ within control text} Other than~\.{@>}, only~\.{@@} is
allowed within control text.

\error{Include file name not given} In an include command, the file name
must be on the same line as the \.{@i}.

\error{Incompatible section names} A section name is not uniquely
distinguishable from another.

\error{Infinite recursion in definition of environmental variable "\dots"}
Either a bug in your logic or in \WEB's.  If you think it's \WEB, please
report it.

\error{Input ended in mid-comment} A ``\.{/*}'' was not followed by a
matching~``\.{*/}''. 

\error{Input ended in middle of embedded comment} Embedded comments are
C-style comments within strings that are delimited by parentheses. (Certain
macros or \&{include} statements treat their arguments as strings.)

\error{Input ended in middle of string beginning with \.'\It{delimiter}\.'}
Found end-of-file before end of string.
 
\error{Input ended in section name} The closing \.{@>} of a section name
was not found.

\error{Input ended in verbatim comment}  A \atcmd{/*} was not followed by
a matching ``\.{*/}''.

\error{Inserted~'$c$' at beginning of continued string} The option~\.{-\\}
is in effect, but the continuation character~$c$ that ended the last line
does not appear as the first non-blank character on the present line.

\error{Invalid escape sequence \.'\.\\\It{c}\.' in ASCII
constant; null assumed} In a construction of the form \.{'\\\It{c}'},
$c$~was not one of~\.0, \.\\, \.', \.", \.?, \.a, \.b, \.f, \.n, \.r, \.t,
or~\.v.

\error{Name does not match} A section name was used that was never defined.

\error{Nested named modules.  Missing \.@?} A construction of the form
\atcmd{<\dots@>=} was found in the code section of a module. Perhaps the
equals sign is spurious or there's a missing \.{@\ } or~\.{@*}.

\error{Not present: \.<\It{section name}\.>} A section name of the form
\.{@<\dots@>} was referenced but never defined.

\error{Output file name not given} You must say \.{@o\ \It{filename}}.

\error{Output file name too long; allowed only $n$~characters} The file
name following an \.{@o}~command is too long.

\error{Section name didn't end} A new module command (\.{@\ } or~\.{@*})
was encountered in the middle of a section name beginning with~\.{@<}.

\error{Section name ended in mid-comment} An \.{@\ } or \.{@*} was
encountered while inside a comment beginning with~``\.{/*}''.

\error{Should use double \.@ within ASCII constant} You should say
`\atcmd{'@@'}'', not ``\.{@'@'}''.

\error{String beginning with \.'\It{delimiter}\.' didn't end} Quoted strings
must end on the same input line as they began, unless they are explicitly
continued by a backslash as the very last character in the line.

\error{TeX line had to be broken} \FTANGLE\ had to insert its own line
break in a \TeX\ input line.  Usually this will be done satisfactorily, but
it's best to check it out.

\error{Too many END DOs} Issued only when the \.{-d}~option is used and the
\&{do}\dots\&{end do} blocks don't match properly. \It{Note: This option is
obsolete; use \Ratfor\ instead.}

\error{Verbatim string didn't end} Verbatim strings (beginning with~\.{@=})
must end on the same line as they began. (They can't be continued with
backslashes.) 

\error{WARNING:  Code mode ended during unbracketed optional argument.
Should there be white space after language command?} If you say
``\.{\dots|@ninteger i|\dots}, the '\.i'~is interpreted as a command-line
type of argument to~\.{@n}.  Leave a space after the~\.{@n}.
^^)error messages!\>{FTANGLE})

\errorclass Errors related to preprocessing and macro processing.
^^(error messages!macros(

\error{Actual number of macro arguments ($m$) does not match number of
def'n ($n$)} \WEB\ macros with a fixed number of arguments (not defined
with an ellipsis) must be called with precisely the same number of
arguments. Macros with a variable number of arguments must be called with
at least as many arguments as explicitly defined.

\error{Adjacent operators \."\It{name1}\ \It{name2}\." not allowed in
expression} For example, you can't say ``\.{A\ ||\ ||\ B}''.

\error{Argument \It{n} of \.{\_TRANSLIT} must be a string} The arguments of
this built-in must be enclosed in quotes.

\error{Argument \It{n} of \.{\_TRANSLIT} doesn't begin with \.{'\It{c}'}}
The delimiter characters for the string arguments of \.{\_TRANSLIT} must
all be the same.

\error{Auto insertion type must be one of \."ibfmps"} The characters
between brackets in \.{@m[\dots]} must be one of \.{ibfmps*}.

\error{Can't have \.{@\#elif} after \.{@\#else}} The order must be
\.{@\#if}\dots\.{@\#elif}\dots\.{@\#elif}\dots\.{@\#else}\dots\.{@\#endif}.

\error{Can't have more than 6 types of automatic insertion material;
remaining ignored} You would get this message if you said \.{@m[*f]\dots},
since the \.{*}~already counts as the six types \.{bifmps}.

\error{Can't negate type \It{name}} You can only apply the \.{!} operator
to numeric types.

\error{Can't take one's complement of type \It{name}; operand converted to
integer} You can only take the one's complement of an integer.

\error{\.{'defined'} ends prematurely} In \WEB\ macros, \.{defined} must be
followed by an identifier.

\error{\.{'defined'} must act on identifier, not type \It{name}} As above.

\error{Expected \.{')'} after ellipsis} Macros with variable numbers of
arguments must be defined with the format ``\.{@m\ A(x,y,...)\
\It{text}}''; no other arguments may follow the ellipsis.

\error{Expected constant after \."\.{\#:}\."} For automatic statement
labelling, you must say \.{\#:\It{n}}, where $n \ge 0$.

\error{Found space instead of ']' after automatic insertion material} The
syntax of an automatic insertion macro is \.{@m[\dots]\ \It{name}\ \It{text}}.

\error{Identifier \."\It{name}\." not allowed as binary operand} Possibly you
forgot to define a macro. For example, in \.{\_EVAL(A+B)}, both~\.A and~\.B
must be \WEB\ macros.

\error{Identifier must follow \.{\#!}; command ignored} In \WEB\ macro
text, the construction \.{\#!\It{name}} means substitute the macro
parameter \It{name} without expanding it.

\error{Identifier must follow \.{\#\&}} The construction \.{\#\&\It{name}}
is intended for internal use by the designer of \FWEB; do not use it.

\error{Identifier must follow \.{@\#undef}} You must say \atcmd{\#undef A},
where \.A~is a macro name.

\error{Ignored out-of-order \.{"\It{preprocessor cmd}"} (mlevel = \It{n})}
There's something wrong with a preprocessor construction. The order must be
\.{@\#if}\dots\.{@\#elif}\dots\.{@\#elif}\dots\.{@\#else}\dots\.{@\#endif}.

\error{Internal function name \."\It{name}\." not defined} Do not use the
construction \.{\#\&}; it's for internal use only.

\error{Invalid data type \It{name} in promotion} A crazy syntax error, or a
bug.

\error{Invalid operand of exponentiate has type \It{name}} There's
something wrong with an exponentiation operation (\.{\^}) in a macro
expression. 

\error{Invalid operand of unary minus has type \It{name}} The unary minus~(\.-)
can only be applied to numeric types.

\error{Invalid preprocessor block structure (level \It{n}).  Missing
\.{@\#endif}?} The definition section ended before an \.{@\#if} statement
was properly terminated. 

\error{Invalid type \It{name} in bit operation. (Macro not defined?)} You
can only apply bit operations such as \.\& or \.{||} to integers.

\error{Invalid statement number offset (\It{n}) after \.{\#:}; 1~assumed} In
the construction \.{\#:\It{n}}, $n$~must satisfy $n \ge 0$.

\error{Invalid token \.{0x\It{XX}} (\.{'\It{c}'}) after \.{\#}} In \WEB\
macro text, only the constructions \.{\#:} or \.{\#!} were expected here.

\error{Invalid token \.{'$c$'} (0x\It{XX}) in expression} There's a syntax
error in an argument to something like an \.{@\#if}.

\error{Invalid type returned from \_eval\_} There's something wrong with
the expression evaluator, or a syntax error in an expression.

\error{Macro after \.{\#!} may not have arguments} The more general case is
not implemented.

\error{Macro buffer full; \It{n} bytes requested for \It{reason}} The macro
expansion buffer overflowed. The size can be increased with the \.{-mb}
option. However, this message may also signify a bug in \FWEB.

\error{Macro definition may not start with \.{'$c$'}; \.{-m} option
ignored} There's trouble with a macro definition from the command line.
Macro names must begin with an alphabetic character, an underscore, or a
dollar sign. 

\error{Macro inner recursion depth exceeded} Either a macro was too
complicated, or a bug permitted an infinite recursion.

\error{Macro outer recursion depth exceeded} As above.

\error{Macro must start with identifier} There's something wrong with a
\WEB\ macro. 

\error{Macro token \.{"\#!"} must be followed by a parameter} In \WEB\
macro text, the construction \.{\#!}\It{name} means substitute the macro
parameter \It{name} without expanding it.

\error{Macro token \.{"\#*"} must be followed by a parameter} In \WEB\
macro text, the construction \.{\#*}\It{name} means stringize the macro
parameter \It{name} without expanding it, and without adding an extra level
of quotes if the parameter is already a quoted string.

\error{Missing argument to token-paste operation. Null assumed} The
operator~\.{\#\#} is not allowed at the very beginning or end of a macro
definition. 

\error{Missing equivalence field while undefining \."\It{name}\."; this
shouldn't happen!} There's trouble in paradise; a bug in \FWEB.

\error{Missing internal function name after \.{\#\&}} The construction
\.{\#\&}\It{name} is intended for internal use by the designer of \FWEB; do
not use it.

\error{Missing macro parameter in definition of macro \."\It{name}\.". Token
\dots\ is invalid; can only have identifiers and commas between (\dots)}
There's something wrong with the argument list of a \WEB\ macro definition.

\error{Missing right paren in definition of macro \."\It{name}\."} Parentheses
didn't match up while processing the argument list of a \WEB\ macro.

\error{Missing \.{'('} in call to macro \."\It{name}\."} This macro was defined
to have arguments, but is used without an argument list.

\error{No \.{')'} in call to macro \."\It{name}\."} In a call to a \WEB\ macro,
the closing parenthesis couldn't be found.

\error{Non-numeric type returned from eval (undefined macro?); assumed
FALSE} The expression evaluator couldn't reduce an expression to~0 or~1.

\error{Non-numeric type returned from neval (undefined macro?); assumed 0}
The expression evaluator couldn't reduce an expression to a number.

\error{Null expression encountered during expression evaluation; 0 assumed}
You would get this message, for example, if you said `\atcmd{\#if()}'.

\error{Only one \.{@\#else} allowed} Only one \.{@\#else} is permitted in
an \.{@\#if} construction. Perhaps you meant to say \.{@\#elif}.

\error{Overriding previous auto insertion type~$c$} Auto insertions for the
same type do not stack.  You said something like
\.{@m[f]} but type~\.f had already appeared in a previous such
construction (possibly implicitly, through a~'\.*').

\error{Right operand of \.{'$c$'} is zero} You can't divide by~0.

\error{Section ended during scan for \.{"@\#else"}, \.{"@\#elif"}, or
\.{"@\#endif"}. Inserted \.{"@\#endif"}. (elevel = \It{n})} A \.{@\ } or
\.{@*} was encountered before a \.{@\#if} was properly closed.

\error{Sorry, @\#pragma command not implemented yet} But you were clever to
try.
 
\error{Too many macro arguments in definition of \."\It{name}\."; MAX\_MARGS =
\It{n}} A maximum of \\{MAX\_MARGS} arguments are allowed for \WEB\ macros.

\error{WARNING:  Command-line language~\It{language} overridden in limbo by
\It{language}} You specified a language on the command line, but a
different one in the file.  Generally, put the language command into the
file.

\error{WARNING: \."\It{name}\." is already undefined} You attempted to
\.{@\#undef} an identifier that was not defined as a \WEB\ macro.
^^)error messages!macros)

\errorclass {\tt Ratfor} errors.
^^(error messages!\>{Ratfor}(

An annoying class of error messages is that which begins with ``Output
ended \dots''. If an expected delimiter is missing, the scan will, at
present, proceed 
to the end of file. Really, it's possible to stop the scan before that, say
at the beginning of the next function; that mechanism will be installed in
future versions. 

\error{Automatic statement number out of bounds; \It{n} assumed} An
automatic statement number bigger than \Fortran's maximum of~99999 was
generated. 

\error{Case value \It{val} of type double truncated to int} Cases should
really be integer expressions.

\error{Can't return value from program or subroutine} The statement
``\.{return \It{expr};}'' is allowed only in functions, not subroutines or
main programs.

\error{Expected identifier after \."\It{name}\."} There's a missing name after
\&{program}, \&{subroutine}, or \&{function}.

\error{Ignored \.{'\It{r}'} not matched with \.{'\It{l}'}} There were too
many right delimiters~$r$ to be matched with the left delimiter~$l$.

\error{Inserted \.{'\{'}} A compound statement was expected here.

\error{Inserted \.{'\It{c}'} after \."\It{name}\."} For example, \&{default}
wasn't followed by its mandatory colon.

\error{Invalid escape sequence '\.\\\It{letter}' in Ratfor character
constant; null assumed} In a construction of the form \.{'\\\It{c}'},
$c$~was not one of~\.0, \.\\, \.', \.", \.?, \.a, \.b, \.f, \.n, \.r, \.t,
or~\.v.

\error{Missing left paren after "\It{name}"; expansion aborted} Certain
keywords such as \&{while} are expected to be followed by a left
parenthesis.

\error{Missing opening delimiter \.{'\It{c}'}; text not copied} A
construction beginning with the character~\It{c} was expected here.

\error{Missing right brace (level \It{n}) at beginning of function; END
statement inserted} A \&{program}, \&{subroutine}, or \&{function}
statement was encountered before the body of a preceding program unit was
properly terminated with a right brace.

\error{Misplaced keyword: \."\It{name}\." must appear inside loop}
For example, \&{next} is allowed only inside loops such as~\&{for}.

\error{Misplaced keyword: \."\It{name}\." must be used only inside
\.{"switch"}} For example, \&{default} is allowed only inside a \&{switch}.

\error{Output ended after \.{'\{'}} End of file was encountered before a
matching right brace was found.

\error{Output ended at beginning of statement} A single or compound
statement was expected here.

\error{Output ended during scan of simple statement} A semicolon to
terminate the statement wasn't found.

\error{Output ended while copying to \.{'\It{r}'}} In some cases, \Ratfor\
copies things directly to the output while searching for a closing
delimiter. In this case, the closing delimiter wasn't found.

\error{Output ended while scanning for \.{'\It{c}'}} Some sort of list,
such as the argument to a \&{for} statement, wasn't properly terminated.

\error{Output ended while skipping newlines} Probably a statement was
expected here. Comments are also skipped while skipping over newlines.

\error{Ratfor character constant longer than one byte; extra characters
ignored} In \Ratfor, as in~C, single quotes denote character constants
whose length is one byte, so
constructions such as \.{'ab'} are not allowed. Perhaps you intended this
to be a character string, which should be enclosed by double quotes:
\.{"ab"}.

\error{Ratfor is not loaded\dots} You linked on the dummy package
\.{ratfor0.o} instead of \.{ratfor.o}.  Therefore, you're not allowed to
set the language to \\{RATFOR}.

\error{Shouldn't encounter top level here} There's something wrong with
\FWEB's stacking mechanism for expanding \Ratfor\ keywords.

\error{Unexpected keyword \."\It{name}\." ignored} For example, an \&{until}
was used without a preceding \&{repeat}.
^^)error messages!\>{Ratfor})

\errorclass General messages from {\tt FWEAVE}.
^^(error messages!\>{FWEAVE}(

\error{\.{@f}~line ends prematurely} For changing category codes, the
syntax is \.{@f\ `$a$\ \t{n}}.

\error{A string must follow~\.{@l}} Where is the text of the limbo text
definition? 

\error{Braces don't balance in comment} This holdover from Knuth's Pascal
\WEB\ is sometimes spurious, and should be improved.

\error{Can't have vertical bars in \.{@!}~compiler directives} A
restriction of the implementation.

\error{Category code must be between~0 and~15}  Just as in \TeX.

\error{Control codes are forbidden in control text} If you need an~\.{@},
you can say ``\.{\\AT!}''.

\error{Control text didn't end} The terminating \.{@>} must be on the same
line as the control text began.

\error{Double \.@ required outside of sections} If you intend for the
character~\.{'@'} to be here, you must double it. Otherwise, you're using a
control code that isn't allowed here.

\error{Double \.@ should be used in strings} No control codes are allowed
inside strings; for the '\.@'~symbol you must say~`\atcmd{@}'.

\error{Identifier was already explicitly defined via~\.{@[} in module~$n$} 
Identifiers should be explicitly defined in only one place.

\error{Illegal use of \.@ in comment} No control codes are allowed in
comments. If you intend the character~'\.@', you must double it.

\error{Implicit declaration of `\It{name}' conflicts with previous
declaration at module~$n$}  The syntax parser recognized a complete
function (during phase~2), but either the function name had already been
identified by an \.{@[}~command in phase~1 or the function has been defined
more than once.

\error{Improper format definition} There are too many or too few items in
an \.{@f} command.

\error{Improper macro definition: expected \.{')'} after ellipsis}
Self-explanatory. 

\error{Improper macro definition: expected identifier} Self-explanatory.

\error{Improper macro definition: unrecognized token in argument list}
Self-explanatory, but the message should be made more explicit.

\error{Input ended in mid-comment} A ``\.{/*}'' was not followed by a
matching~``\.{*/}''. 

\error{Input ended in middle of string beginning with '\It{delimiter}'}
Found end-of-file before end of string.
 
\error{Input ended in section name} The closing \.{@>} of a section name
was not found.

\error{Inserted~$c$ at beginning of continued string} The option~\.{-\\}
is in effect, but the continuation character~$c$ that ended the last line
does not appear as the first non-blank character on the present line.

\error{Invalid \.{@f} command:  One of the representation~\.{`a}, \.{`\\a},
or~\.{`\^\^M} is required} A left quote appears after~\.{@f} says that you
want to change a \TeX\ category code.  Use the same syntax for the
character whose catcode is to be changed as you would following \TeX's
\.{\\catcode} command.

\error{Invalid category code} A numerical constant was expected here.

\error{Invalid op code~$n$} There's something wrong with the operator being
processed.  If you can't figure this one out, please report it.

\error{Missing \.{'|'} after code text} Did you forget to switch out of
code mode in the middle of \TeX\ text?

\error{No op\_macro name for "\dots" [\It{language}]; token ignored}
There's something funny about an operator overload.  If you can't figure
this out, please report it.

\error{Operator after~\.{@v} is invalid} There's something wrong with the
operator after an \.{@v}~command.  Dot constants should be written
\It{sans} dots; characters such as parentheses are not valid operators. 

\error{Second argument (replacement text) of~\.{@v} must be a quoted
string} The syntax of an operator overload command is \.{@v\ \It{newop}\
"\It{string}"\ \It{oldop}}.

\error{Section ended in middle of Fortran-90 continuation} \WEB\ thinks the
last line was a continuation (ended by the continuation character~'\.\\'
or~'\.\&'), but then reached end-of-file.

\error{Section name didn't end} A new module command (\.{@\ } or~\.{@*})
was encountered in the middle of a section name beginning with~\.{@<}.

\error{String beginning with \.'\It{delimiter}\.' didn't end} Quoted strings
must end on the same input line as they began, unless they are explicitly
continued by a backslash as the very last character in the line.

\error{String must follow~\.{@l}} Limbo text commands have the form
`\atcmd{l\ "abc\\ndef"}'.

\error{TeX string should be in code text only} An \.{@t} command is misplaced.

\error{Verbatim string didn't end} Verbatim strings (beginning with~\.{@=})
must end on the same line as they began. (They can't be continued with
backslashes.) 

\error{You can't do that in code text} Commands like \.{@d} or \.{@f} are
not allowed here.

\error{You can't do that in TeX text} The following commands are not
allowed in \TeX\ text: \.{@,}, \.{@|}, \.{@/}, \.{@\#}, \.{@+}, \.{@\&},
\.{@;}, \.{@e}, \.{@:}.

\error{You need an \.= sign after the section name} Self-explanatory. One
sometimes gets this error if \FWEAVE\ has gotten confused about which part
of the section it's in.

\error{You should say \.{@@}} Don't forget to double the~\.{@}'s in \WEB\
source code.

\error{You should say \.{\\@@}} The single-character \TeX\ macro~\.{\\@}
must be written in \WEB\ source code as~\.{\\@@}.
^^)error messages!\>{FWEAVE})
^^)error messages)

\Knuth
\appendix K: GETTING {\tt WEB} ONTO a NEW COMPUTER.[INSTALLATION]
^^[installation]

\endKnuth

\[The following paragraph, extracted from Knuth's original report,  is
included here mostly for entertainment.\] 

\KNUTH
``If you have only the present report, not a tape, you will have to prepare
files \.{WEAVE.WEB} and \.{TANGLE.WEB} by hand, typing them into the
computer by following Appendices~D and~E. Then you have to simulate the
behavior of \.{TANGLE} by converting \.{TANGLE.WEB} manually into
\.{TANGLE.C}; with a good text editor this takes about six hours. Then
you have to correct errors that were made in all this hand work; but still
the whole project is not impossibly difficult, because in fact the entire
development of \.{WEAVE} and \.{TANGLE} (including the writing of the
programs and the manual) took less than two months of work.''
\It{[Note from J.~A. Krommes: {\rm(!!!)}]}
\endKNUTH

\input guide0 % Bring in the material from the reference guide.

